このクイックスタートでは、Data Manager API について説明します。表示するクイックスタートのバージョンを選択します。
このクイックスタートでは、次の手順を行います。
- オーディエンス データを受け取る
Destinationを準備します。 - 送信するオーディエンス データを準備します。
- オーディエンス メンバーの
IngestionServiceリクエストを作成します。 - Google APIs Explorer でリクエストを送信します。
- 成功レスポンスと失敗レスポンスを理解する。
移行先を準備する
データを送信する前に、データを送信する宛先を準備する必要があります。使用できる Destination のサンプルを次に示します。さまざまなシナリオの宛先の例については、宛先を構成するをご覧ください。
{
"operatingAccount": {
"accountType": "OPERATING_ACCOUNT_TYPE",
"accountId": "OPERATING_ACCOUNT_ID"
},
"loginAccount": {
"accountType": "LOGIN_ACCOUNT_TYPE",
"accountId": "LOGIN_ACCOUNT_ID"
},
"productDestinationId": "AUDIENCE_ID"
}
operatingAccountを、オーディエンス データを受け取るアカウントのアカウント タイプと ID に設定します。- OAuth 認証情報が Google 広告クライアント センター（MCC）アカウントにアクセスできるユーザーのもので、その MCC アカウントのサブアカウントの 1 つが
operatingAccountである場合は、loginAccountを MCC アカウントのアカウント タイプと ID に設定します。 - OAuth 認証情報が
operatingAccountに直接アクセスできるユーザーのものである場合は、loginAccountを設定する必要はありません。
オーディエンス データを準備する
カンマ区切りファイルの次のサンプルデータを考えてみましょう。ファイルの各行はオーディエンスの 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,
メールアドレスには、次の形式とハッシュ化の要件があります。
- 先頭、末尾、中間にあるすべての空白を削除します。
- メールアドレスを小文字に変換します。
- SHA-256 アルゴリズムを使用してメールアドレスをハッシュ化します。
- ハッシュ バイトは、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"
}
]
}
}
リクエストの本文を作成する
リクエストの本文を作成するには、destinations と audienceMembers を組み合わせて encoding フィールドを設定し、validateOnly や consent など、含めるリクエスト フィールドを追加します。
顧客一致でオーディエンス メンバーを送信する場合は、termsOfService を設定して、ユーザーが顧客一致の利用規約に同意しているかどうかを示します。
このガイドの例では暗号化を使用していませんが、ユーザーデータを暗号化するの手順に沿って、プロセスに暗号化を追加できます。
リクエストを送信する
- [API Explorer で開く] をクリックして、新しいタブまたはウィンドウで API Explorer を開きます。
- API エクスプローラの本文で、
REPLACE_WITHで始まる各文字列（REPLACE_WITH_OPERATING_ACCOUNT_TYPEなど）を関連する値に置き換えます。 - API エクスプローラ ページの下部にある [実行] をクリックし、認証プロンプトに沿って操作してリクエストを送信します。
validateOnlyをtrueに設定して、変更を適用せずにリクエストを検証します。変更を適用する準備ができたら、validateOnlyをfalseに設定します。
取り込みリクエスト
{ "destinations": [ { "operatingAccount": { "accountType": "OPERATING_ACCOUNT_TYPE", "accountId": "OPERATING_ACCOUNT_ID" }, "loginAccount": { "accountType": "LOGIN_ACCOUNT_TYPE", "accountId": "LOGIN_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 }
成功したレスポンス
リクエストが成功すると、requestId を含むオブジェクトを含むレスポンスが返されます。
{
"requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}
返された requestId を記録して、リクエスト内の各宛先が処理されるときに診断を取得できるようにします。
失敗レスポンス
リクエストが失敗すると、400 Bad
Request などのエラー レスポンス ステータス コードと、エラーの詳細を含むレスポンスが返されます。
たとえば、16 進数エンコード値ではなくプレーン テキスト文字列を含む emailAddress は、次のレスポンスを生成します。
{
"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 進数エンコードのみが行われた emailAddress は、次のレスポンスを生成します。
{
"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"
}
]
}
]
}
}
複数の宛先にイベントを送信する
データに異なる宛先のオーディエンス メンバーが含まれている場合は、宛先参照を使用して同じリクエストで送信できます。
たとえば、ユーザーリスト ID 11112222 のオーディエンス メンバーと、ユーザーリスト ID 77778888 のオーディエンス メンバーがいる場合は、各 Destination の reference を設定して、両方のオーディエンス メンバーを 1 つのリクエストで送信します。reference はユーザー定義です。各 Destination に一意の reference があることが唯一の要件です。リクエストの変更後の destinations リストは次のとおりです。
"destinations": [
{
"operatingAccount": {
"accountType": "OPERATING_ACCOUNT_TYPE",
"accountId": "OPERATING_ACCOUNT_ID"
},
"loginAccount": {
"accountType": "LOGIN_ACCOUNT_TYPE",
"accountId": "LOGIN_ACCOUNT_ID"
},
"productDestinationId": "11112222",
"reference": "audience_1"
},
{
"operatingAccount": {
"accountType": "OPERATING_ACCOUNT_2_TYPE",
"accountId": "OPERATING_ACCOUNT_2_ID"
},
"loginAccount": {
"accountType": "LOGIN_ACCOUNT_2_TYPE",
"accountId": "LOGIN_ACCOUNT_2_ID"
},
"productDestinationId": "77778888",
"reference": "audience_2"
}
]
各 AudienceMember の destination_references を設定して、1 つ以上の特定の宛先に送信します。たとえば、最初の Destination のみの AudienceMember は次のようになります。この場合、destination_references リストには最初の Destination の reference のみが含まれます。
{
"userData": {
"userIdentifiers": [
{
"emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
},
{
"emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
}
],
}
"destinationReferences": [
"audience_1"
]
}
destination_references フィールドはリストであるため、オーディエンス メンバーに複数の宛先を指定できます。AudienceMember の destination_references を設定しない場合、Data Manager API はリクエスト内のすべての宛先にオーディエンス メンバーを送信します。
次のステップ
- クライアント ライブラリを使用して認証を構成し、環境を設定します。
- 各データタイプの形式、ハッシュ化、エンコードの要件について説明します。
- ユーザーデータを暗号化する方法を学習する。
- リクエストの診断情報を取得する方法を確認する。
- ベスト プラクティスについて確認する。
- 上限と割り当てについて学習する。