Amazon Bedrock AI コネクタ構成ガイド

サポートされているモデル

Amazon Bedrock AI コネクタは、多くの基盤モデルをサポートしています。現在サポートされているモデルのリストについては、Amazon Bedrock: Amazon Bedrockでサポートされている基盤モデルを参照してください。

一部のBedrockモデルはプロビジョニングされたスループットが必要であり、オンデマンド推論を使用して呼び出すことはできません。オンデマンドスループットエラーが発生した場合は、ON_DEMAND 推論をサポートするモデルを使用するか、構成リストにプロビジョニングされたスループットまたは推論プロファイルARNを提供してください。

IAM ロールと権限の作成

Tealiumは、サーバーサイドコネクタからAmazon Bedrockに接続するために、AWSアカウント内のIAMロールと権限が必要です。接続の認証には2つのオプションがあります：

• アクセスキーとアクセスシークレットを提供する。
• STSクレデンシャルを提供する。

アクセスキーとシークレットクレデンシャル

AWSアクセスキーとシークレットを作成するには：

1. AWS管理コンソールにログインし、IAM（Identity and Access Management）サービスに移動します。
2. ユーザー をクリックし、ユーザーを追加 をクリックします。
3. ユーザー名を入力します。例：TealiumBedrockUser。
4. ユーザーにポリシーをアタッチします。詳細については、ポリシーをアタッチするを参照してください。
5. キーを作成します。
   • セキュリティ認証情報 タブに移動し、アクセスキーの作成 をクリックします。
   • アクセスキーID と シークレットアクセスキー をコピーし、安全に保存します。

STSクレデンシャル

STSクレデンシャルを作成するには：

1. AWS管理コンソールにログインし、IAM（Identity and Access Management）サービスに移動します。
2. ロール をクリックし、ロールの作成 をクリックします。
3. 信頼されたエンティティタイプ で、AWSアカウントを選択します。
4. 別のAWSアカウント を選択し、TealiumアカウントID：757913464184 を入力します。
5. （オプション）外部IDが必要 チェックボックスを選択し、使用する外部IDを指定します。外部IDは最大256文字で、英数字（A-Z, a-z, 0-9）およびハイフン（-）、アンダースコア（_）、ピリオド（.）などの記号を含めることができます。
6. ロールの名前を入力します。ロール名は TealiumBedrock で始まる必要があります。例：TealiumBedrock-RoleName。
7. ロールにポリシーをアタッチします。詳細については、ポリシーをアタッチするを参照してください。
8. 信頼ポリシーを作成します。
   • 信頼関係 タブに移動し、信頼関係を編集 をクリックします。
   • 作成したロールを使用して特定の外部IDがロールを使用できるように信頼ポリシーを構成し、Tealiumの本番アカウントIDが 757913464184 であることを確認します。
   • Tealiumへの接続に使用する EXTERNAL_ID 値を構成します。IDは最大256文字で、英数字（A-Z, a-z, 0-9）およびハイフン（-）、アンダースコア（_）、ピリオド（.）などの記号を含めることができます。

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::757913464184:root"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "EXTERNAL_ID"
            }
          }
        }
      ]
    }

ポリシーをアタッチする

AWS管理コンソールで、コネクタのアクションに必要なポリシーを入力します。各コネクタアクションには次のポリシーが必要です：

必要なフローやLambda関数の特定のARNに対してのみ権限を制限することをお勧めします。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListModels",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListFoundationModels"
      ],
      "Resource": "*"
    },
    {
      "Sid": "InvokeModel",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RenderManagedPrompt",
      "Effect": "Allow",
      "Action": [
        "bedrock:RenderPrompt"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockFlowInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeFlow"
      ],
      "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:flow/<flow_id>/alias/<alias_name>"
    },
    {
      "Sid": "LambdaInvokeFunction",
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeFunction"
      ],
      "Resource": "arn:aws:lambda:<REGION>:<ACCOUNT_ID>:function:<FUNCTION_NAME>"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockFlowInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeFlow"
      ],
      "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:flow/<flow_id>/alias/<alias_name>"
    }
  ]
}

ポリシーを入力してアタッチするには：

1. AWSコンソールで IAM > ポリシー に移動します。
2. ポリシーの作成 をクリックします。
3. ポリシーエディタで JSON タブを選択します。
4. エディタにコネクタアクションのポリシーを貼り付けます。
5. 任意の検証警告を解決し、次へ をクリックします。
6. ポリシー名（例：TealiumCustomAccessPolicy）とオプションの説明を入力します。
7. ポリシーの作成 をクリックします。
8. ロール に移動します。
9. 変更したいロール名をクリックします。
10. 権限 タブで 権限の追加 > ポリシーのアタッチ をクリックします。
11. 検索ボックスに新しいカスタムポリシーの名前を入力します。
12. そのポリシーのボックスを選択します。
13. ポリシーのアタッチ をクリックします。

構成

コネクタマーケットプレイスに移動し、新しいコネクタを追加します。コネクタを追加する一般的な手順については、コネクタについてを参照してください。

コネクタを追加した後、次の構成を構成します：

• 認証タイプ：（必須）使用する認証のタイプ。
  • アクセスキー
    • アクセスキー：（必須）IAMユーザーのアクセスキーを提供します。関連するIAMポリシー（IAMユーザーまたは想定されるロール用）は、データを送信するストリームとともに bedrock:PutRecord 権限を付与する必要があります。
    • シークレットキー：（必須）IAMユーザーのシークレットキーを提供します。
  • STS
    • STS - Assume Role: ARN：（必須）想定するロールに割り当てられたAmazonリソースネーム。詳細については、AWS: IAMロールへの切り替えを参照してください。
    • STS - Assume Role: Session Name：（必須）想定されるロールセッションの一意の識別子。
    • STS - Assume Role: External ID：（オプション）第三者が顧客のアカウントでロールを想定する際に使用する一意の識別子。詳細については、AWS: 第三者が所有するAWSアカウントへのアクセスを参照してください。
• リージョン：（必須）リージョンを選択します。

プロンプト情報

Tealiumから送信されたり、Amazon Bedrock内で管理されたり、フローで使用されたりするBedrock AIプロンプトは、Tealiumがレスポンスを正しく処理できるように、有効なJSONのみを返すように作成する必要があります。以下のガイドラインに従ってください：

• マップされたパラメータを参照するには二重中括弧を使用します。例：{{tealium_account}}、{{tealium_profile}}、{{tealium_visitor_id}}、{{visitor_json}}。
• モデルに対して、説明、マークダウン、コードフェンス、JSONの前後の余分なテキストなしに、有効なJSONのみを返すように明確に指示します。
• 期待する正確なJSON構造（フィールド名、必要なキー、値のタイプ）を定義して、出力を安全に解析できるようにします。
• Tealiumフィールドを明示的に返すようにモデルに指示します（例：tealium_account、tealium_profile、tealium_visitor_id、tealium_event）。
• プロンプトで特定の属性を参照する必要がある場合は、その属性をベンダーパラメータにマップします。例えば、Last product viewedをlast_product_viewedにマップし、プロンプトで{{last_product_viewed}}として参照します。
• 曖昧な指示を避けます。繰り返し呼び出しても同じJSONスキーマを生成する決定論的なプロンプトを記述します。
• 最良の結果を得るために、次のような行を含めます：“単一のJSONオブジェクトのみを返し、散文、バックティック、追加のフォーマットは含まないでください。”

プロンプト例

あなたは、有効なJSONのみを返す必要があるAIアシスタントです。
説明、マークダウン、コードフェンス、またはJSONオブジェクトの外のテキストを含めないでください。

以下の訪問データを使用して、このセッションでの訪問の変換可能性を0から100の間の数値で計算します。

単一のJSONオブジェクトのみを返し、この正確な構造で：

{
  "tealium_account": "{{tealium_account}}",
  "tealium_profile": "{{tealium_profile}}",
  "tealium_visitor_id": "{{tealium_visitor_id}}",
  "tealium_event": "bedrock_ai_insight",
  "visitor_score": <0から100の間の整数>
}

訪問データ：
{{visitor_json}}

{{last_product_viewed}}の値に特に注意してください。

レスポンスは以下のようになります：

{
    "metrics": {
        "latencyMs": 1272
    },
    "output": {
        "message": {
            "content": [
                {
                    "text": "{\"tealium_account\":\"your-account\",\"tealium_profile\":\"main\",\"tealium_visitor_id\":\"__your-account_main__5574_438850__\",\"tealium_event\":\"bedrock_ai_insight\",\"visitor_score\":85}"
                }
            ],
            "role": "assistant"
        }
    },
    "stopReason": "end_turn",
    "usage": {
        "inputTokens": 8811,
        "outputTokens": 65,
        "serverToolUsage": {},
        "totalTokens": 8876
    }
}

コネクタはレスポンスを受け取り、JSONイベントオブジェクトをTealium Collect APIエンドポイントに送信します。

Amazon Bedrockフロー

Amazon Bedrockフローは、プロンプト、ナレッジベース、Lambda関数、条件ロジック、外部データを組み合わせた複数ステップのAIオーケストレーションです。フローは、複雑なAI意思決定を単一のAPIエンドポイントに変換するために、入力データがプロンプト、エンリッチメントステップ、ビジネスロジック、最終出力を通過する方法を定義します。

Send Data to Bedrock Flowアクションを使用するには、Tealiumから入力を受け取り、AIステップを処理して、Lambda関数を通じてTealiumに結果を送り返すAmazon Bedrockフローを作成します。

以下のセクションでは、フローの必須およびオプションのコンポーネントについて説明します。

ステップ1 - フロー入力の定義

すべてのフローは入力ノードから始まります。このノードは、Tealiumがフローに送信するJSONドキュメントを表します。

Tealiumは、次の例に似た形式でマップされた属性を送信します：

"document": {
    "tealium_account": "services-example",
    "tealium_profile": "ai",
    "tealium_visitor_id": "1234567890abc",
    "visitor_profile": {
        "lifetime_value": "1200",
        "total_orders": 5,
        ...
        }
}

フロー内でフィールドを参照するには、$.data.attribute_nameを使用します。前の例に基づいて：

ステップ2 - プロンプトノードにデータをマップする（必須）

次に、AI出力（スコア、推奨事項、または決定など）を生成するプロンプトノードを追加します。

プロンプトノード内で：

1. プロンプトテキストを構成します。
2. {{fieldname}}形式を使用して変数を挿入します。例：{{tealium_account}}。
3. Bedrockモデルを選択します。
4. プロンプトの出力として有効なJSONを返します。

例については、上記のプロンプト例セクションを参照してください。

ステップ3 - （オプション）ナレッジベースの取得を追加

Amazon Bedrockナレッジベースを使用すると、AIワークフローをAmazon S3、Amazon Redshift、またはAmazon OpenSearch Serviceなどの外部データソースに接続できます。ナレッジベースはドキュメントを保存およびインデックス化し、プロンプト実行中の取得および接地に使用できるようにします。このステップはオプションですが、パーソナライゼーション、推奨事項、またはコンテキストに基づく意思決定には価値があります。

ナレッジベースを接続した後、{{$.kbResults}}のようなフィールドを使用して、ナレッジベースの結果をプロンプトに渡すことができます。

ナレッジベースに関する詳細は、Amazon Bedrock: Retrieve data and generate AI responses with Amazon Bedrock Knowledge Basesを参照してください。

ナレッジベースの作成に関する詳細は、Amazon Bedrock: Create a knowledge base by connecting to a data source in Amazon Bedrock Knowledge Basesを参照してください。

ステップ4 - Tealiumへの結果を送り返すためのLambdaノードを追加（Tealium統合には必須）

プロンプトが構造化されたJSONを生成した後、その結果をプロファイルエンリッチメントのためにTealiumに送り返す必要があります。

Lambdaノードを追加して：

• プロンプトノードからの出力（$.data）を受け取ります。
• JSONを解析します。
• Tealium Collectに投稿します：POST https://collect.tealiumiq.com/event。
• 次のものを含めます：
  • tealium_account
  • tealium_profile
  • tealium_visitor_id
  • tealium_event（ユーザー定義）
  • AI出力フィールド（例：visitor_score）

提供されたLambda例を使用するか、独自のものを構築してください。

ステップ5 - フロー出力ノードを追加

TealiumはフローのAPIレスポンスを処理しませんが、出力ノードはフローを完了するために必要です。

Lambda出力をFlowOutputNodeに接続することはTealiumの処理には影響しませんが、次のツールを使用してフローが機能していることを確認するのに役立ちます：

• Bedrockコンソールでのデバッグ。
• Lambda関数からのエラーの表示。
• 検証のための最終JSON結果の検査。
• Traceを使用したTealiumでの出力の表示。

Lambdaの例

以下は、プロンプト出力を受け入れ、JSONを解析し、TealiumのCollectエンドポイントにデータを送信してエンリッチメントとアクティベーションを行うLambdaの例です。さまざまなデータ構造を考慮したフォールバックが含まれています。必要に応じて書き換えてください。

アカウントとプロファイルは、指定されたデータソースでサーバーサイドイベントを受け入れるように構成する必要があります。

この例は、ランタイム環境としてNode.jsバージョン18.x以降を必要とします。

const COLLECT_URL = process.env.COLLECT_URL || "https://collect.tealiumiq.com/event";
function extractInputByName(event, name) {
  const arr = event?.node?.inputs;
  if (Array.isArray(arr)) {
    const hit = arr.find(i => i?.name === name);
    if (hit && typeof hit.value === "string") return hit.value;
    if (hit && typeof hit.value === "object") return JSON.stringify(hit.value);
  }
  return undefined;
}
function extractJsonStringFromEvent(event) {
  const fromStandardPin = extractInputByName(event, "codeHookInput");
  if (typeof fromStandardPin === "string") return fromStandardPin;
  const anyString = event?.node?.inputs?.find?.(i => typeof i?.value === "string")?.value;
  if (typeof anyString === "string") return anyString;
  if (typeof event?.codeHookInput === "string") return event.codeHookInput;
  if (typeof event?.document === "string") return event.document;
  const doc = event?.fields?.[0]?.content?.document;
  if (typeof doc === "string") return doc;
  if (typeof event === "string") return event;
  throw new Error("Could not find JSON string in event");
}
export const handler = async (event) => {
  try {
    const jsonStr = extractJsonStringFromEvent(event);
    const obj = JSON.parse(jsonStr);  // Fixed: store parsed result
    const required = ["tealium_account", "tealium_profile", "tealium_visitor_id"];
    for (const key of required) {
      if (!Object.prototype.hasOwnProperty.call(obj, key)) {
        throw new Error(`Missing required field '${key}' in model output`);
      }
    }
    const r = await fetch(COLLECT_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: jsonStr
    });
    if (!r.ok) {
      const txt = await r.text().catch(() => "");
      throw new Error(`Collect failed ${r.status}: ${txt}`);
    }
    return jsonStr;
  } catch (err) {
    console.error("Shim error:", err);
    return JSON.stringify({ ok: false, error: String(err.message || err) });
  }
};

アクション

次のセクションでは、各アクションのパラメータとオプションの構成方法について説明します。

Bedrock AIモデルへのプロンプト送信

パラメータ

Bedrock AI管理プロンプトへのデータ送信

Bedrock AIフローへのデータ送信

一般的なエラーとトラブルシューティング

以下は一般的なエラーコードと解決策です：

AWSの一般的なエラーコード：

• AccessDeniedException または NotAuthorized
  IAMユーザーまたはロールに必要な権限がありません（例：bedrock:InvokeModel、bedrock:RenderPrompt、bedrock:InvokeFlow、bedrock:ListFoundationModels）。
  これを解決するには、ロールまたはアクセスキーに添付されているIAMポリシーを更新して、必要なBedrockアクションを正しいリソースに含めます。

• InvalidClientTokenId、UnrecognizedClientException、または ExpiredTokenException
  構成されたアクセスキーまたはSTSセッションが無効または期限切れです。
  これを解決するには、コネクタで資格情報を回転させて再入力するか、STSロールと外部IDが正しく期限切れでないことを確認します。

• OptInRequired または FTUFormNotFilled
  AWSアカウントがBedrockまたは特定のモデル（例：Anthropic）に完全に有効化されていません。
  これを解決するには、AWSコンソールで必要なBedrock有効化ステップと任意のモデル固有のフォームまたはマーケットプレイスのサブスクリプションを完了します。

これらのエラーが表示された場合は、まずAWSでIAMまたはアカウント構成を解決してください。権限が修正されるまでコネクタアクションを再試行しても成功しません。

Bedrock API呼び出しからの一般的なエラー

以下のエラーは、リクエストがBedrockに到達したが、サービスまたはモデルが正常に完了できなかったことを意味します。

• ValidationException または ValidationError
  リクエストボディまたはパラメータがターゲットモデルまたはAPIに無効です（例：間違ったモデルID、サポートされていないパラメータ、入力が大きすぎる）。
  これを解決するには、モデルID / プロンプトARN / フローARNを確認し、リクエストボディがモデルの期待されるスキーマと一致することを確認し、必要に応じてプロンプトのサイズや最大トークン数を減らします。

• ResourceNotFound または ResourceNotFoundException
  指定されたモデル、プロンプトバージョン、またはフローエイリアスARNが存在しないか、その地域で利用できません。
  これを解決するには、コネクタ構成のARNと地域をBedrockコンソールに表示されている値と照合して再確認します。

• ThrottlingException または ServiceQuotaExceededException
  あなたの呼び出しがBedrockのクォータを超えています（例：TPSまたはトークン制限）。
  これを解決するには、呼び出し頻度を減らすか、AWSでクォータ増加をリクエストします。

• ServiceUnavailable、InternalFailure、または InternalServerException
  Bedrock内の一時的または内部エラーです。
  これを解決するには、エラーが持続する場合はAWSサービスヘルスダッシュボードを確認するか、AWSサポートケースを開きます。

• ModelErrorException、ModelNotReadyException、または ModelTimeoutException（プロンプトまたは管理されたプロンプトフロー）
  モデルが失敗した、まだウォーミングアップ中、または応答に時間がかかりすぎました。
  これを解決するには、待って再試行し、プロンプトを簡素化するかトークン使用を減らし、モデルまたはプロビジョニングされたスループットが完全にアクティブであることを確認します。

これらのエラーについては、TealiumがBedrockからの元のAWSエラーメッセージを表示するので、トラブルシューティング時にAWSのドキュメントと照合できます。