オーディエンス メンバーを送信する

このクイックスタートでは、Data Manager API について説明します。表示するクイックスタートのバージョンを選択します。

このクイックスタートでは、次の手順を行います。

  1. オーディエンス データを受け取る Destination を準備します。
  2. 送信するオーディエンス データを準備します。
  3. オーディエンス メンバーの IngestionService リクエストを作成します。
  4. Google APIs Explorer を使用してリクエストを送信します。
  5. 成功レスポンスと失敗レスポンスの違いを理解する。

移行先を準備する

データを送信する前に、データを送信する宛先を準備する必要があります。使用できる Destination のサンプルを次に示します。

    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

  • operatingAccount は、オーディエンス データを受信するアカウントのプロダクトと ID に設定します。

視聴者データを準備する

カンマ区切りファイルの次のサンプルデータについて考えてみましょう。ファイルの各行はオーディエンスの 1 人のメンバーに対応し、各メンバーには最大 3 つのメールアドレスがあります。

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

メールアドレスには、次の形式とハッシュ化の要件があります。

  1. 先頭、末尾、中間の空白をすべて削除します。
  2. メールアドレスを小文字に変換します。
  3. SHA-256 アルゴリズムを使用してメールアドレスをハッシュ化します。
  4. 16 進数（hex）または Base64 エンコードを使用して、ハッシュバイトをエンコードします。このガイドの例では、16 進数エンコードを使用しています。

フォーマットされたデータは次のようになります。

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

ハッシュ化とエンコード後のデータを以下に示します。

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

入力データの最初の行にある dana@example.com と danam@example.com の形式設定済み、ハッシュ化済み、エンコード済みのメールアドレスの AudienceMember の例を次に示します。

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

リクエスト本文を作成する

リクエスト本文の Destination と userData を組み合わせます。

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}
  1. 本文のプレースホルダ（OPERATING_ACCOUNT_PRODUCT、OPERATING_ACCOUNT_ID、AUDIENCE_ID など）を、アカウントと宛先の値に更新します。
  2. 変更を適用せずにリクエストを検証するには、validateOnly を true に設定します。変更を適用する準備ができたら、validateOnly を false に設定します。
  3. ユーザーがカスタマー マッチの利用規約に同意したことを示すように termsOfService を設定します。
  4. このリクエストは、consent が付与されていることを示しており、暗号化は使用しません。

リクエストを送信する

  1. サンプルの右上にあるコピーボタンを使用して、リクエスト本文をコピーします。
  2. audienceMembers.ingest ページに移動します。
  3. 右側の [API] ボタンをクリックし、展開されたセクションの [試してみる] ボタンをクリックします。
  4. コピーしたリクエスト本文を [Request body] ボックスに貼り付けます。
  5. [Execute] ボタンをクリックし、承認プロンプトを完了してレスポンスを確認します。

成功レスポンス

リクエストが成功すると、requestId を含むオブジェクトを含むレスポンスが返されます。

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

障害レスポンス

リクエストが失敗すると、400 Bad Request などのエラー レスポンス ステータス コードと、エラーの詳細を含むレスポンスが返されます。

たとえば、16 進数でエンコードされた値ではなく、プレーンテキスト文字列を含む email_address は、次のレスポンスを生成します。

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

ハッシュ化されず、16 進数でエンコードされた email_address は、次のレスポンスを生成します。

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

次のステップ