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

このクイックスタートでは、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. ツールバーの [API] ボタンをクリックします。
  3. コピーしたリクエスト本文を [リクエストの本文] ボックスに貼り付けます。
  4. [実行] ボタンをクリックし、承認プロンプトを完了して、レスポンスを確認します。

成功したレスポンス

リクエストが成功すると、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"
          }
        ]
      }
    ]
  }
}

次のステップ