Mengirim anggota audiens

Anda dapat mempelajari panduan memulai ini untuk memahami Data Manager API. Pilih versi panduan memulai cepat yang ingin Anda lihat:

Dalam panduan memulai ini, Anda akan menyelesaikan langkah-langkah berikut:

  1. Siapkan Destination untuk menerima data audiens.
  2. Siapkan data audiens untuk dikirim.
  3. Buat permintaan IngestionService untuk anggota audiens.
  4. Kirim permintaan dengan Google APIs Explorer.
  5. Memahami respons berhasil dan gagal.

Menyiapkan tujuan

Sebelum dapat mengirim data, Anda harus menyiapkan tujuan untuk mengirim data ke tujuan tersebut. Berikut contoh Destination yang dapat Anda gunakan. Lihat Mengonfigurasi tujuan untuk mengetahui contoh tujuan untuk berbagai skenario.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }
  • Tetapkan operatingAccount ke jenis akun dan ID akun yang akan menerima data audiens.
  • Jika kredensial OAuth Anda ditujukan untuk pengguna dengan akses ke akun pengelola Google Ads, yang memiliki operatingAccount sebagai salah satu sub-akunnya, tetapkan loginAccount ke jenis dan ID akun pengelola.
  • Jika kredensial OAuth ditujukan untuk pengguna dengan akses langsung ke operatingAccount, Anda tidak perlu menyetel loginAccount.

Menyiapkan data audiens

Pertimbangkan contoh data berikut dalam file yang dipisahkan koma. Setiap baris dalam file sesuai dengan satu anggota audiens, dan setiap anggota memiliki hingga tiga alamat email.

#,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,

Alamat email memiliki persyaratan pemformatan dan hashing berikut:

  1. Hapus semua spasi kosong di awal, akhir, dan di antara kata.
  2. Konversi alamat email menjadi huruf kecil.
  3. Beri hash pada alamat email menggunakan algoritma SHA-256.
  4. Enkode byte hash menggunakan hexadesimal (hex) atau encoding Base64. Contoh dalam panduan ini menggunakan encoding hex.

Berikut data yang diformat:

#,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,

Berikut data setelah di-hash dan dienkode:

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

Berikut adalah contoh AudienceMember untuk alamat email dana@example.com dan danam@example.com yang diformat, di-hash, dan dienkode dari baris pertama data input:

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

Buat isi permintaan

Untuk membuat isi permintaan, gabungkan destinations dan audienceMembers, tetapkan kolom encoding, dan tambahkan kolom permintaan lain yang ingin Anda sertakan seperti validateOnly dan consent.

Jika mengirim anggota audiens untuk Customer Match, tetapkan termsOfService untuk menunjukkan apakah pengguna telah menyetujui persyaratan layanan Customer Match.

Contoh dalam panduan ini tidak menggunakan enkripsi, tetapi Anda dapat mengikuti petunjuk di Mengenkripsi data pengguna untuk menambahkan enkripsi ke proses Anda.

Kirim permintaan

  1. Klik Open in API Explorer untuk membuka API Explorer di tab atau jendela baru.
  2. Di isi permintaan di API Explorer, ganti setiap string yang diawali dengan REPLACE_WITH, seperti REPLACE_WITH_OPERATING_ACCOUNT_TYPE, dengan nilai yang relevan.
  3. Klik Execute di bagian bawah halaman API Explorer dan selesaikan perintah otorisasi untuk mengirim permintaan.
  4. Tetapkan validateOnly ke true untuk memvalidasi permintaan tanpa menerapkan perubahan. Jika Anda sudah siap untuk menerapkan perubahan, tetapkan validateOnly ke false.

Permintaan penyerapan

Buka di API Explorer 
{
    "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
}

Respons keberhasilan

Permintaan yang berhasil akan menampilkan respons dengan objek yang berisi requestId.

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

Catat requestId yang ditampilkan sehingga Anda dapat mengambil diagnostik saat setiap tujuan dalam permintaan diproses.

Respons kegagalan

Permintaan yang gagal akan menghasilkan kode status respons error seperti 400 Bad Request, dan respons dengan detail error.

Misalnya, emailAddress yang berisi string teks biasa, bukan nilai yang dienkode hex, akan menghasilkan respons berikut:

{
  "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"
          }
        ]
      }
    ]
  }
}

emailAddress yang tidak di-hash dan hanya dienkode hex menghasilkan respons berikut:

{
  "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"
          }
        ]
      }
    ]
  }
}

Mengirim peristiwa untuk beberapa tujuan

Jika data Anda berisi anggota audiens untuk tujuan yang berbeda, Anda dapat mengirimkannya dalam permintaan yang sama dengan menggunakan referensi tujuan.

Misalnya, jika Anda memiliki anggota audiens untuk ID daftar pengguna 11112222 dan anggota audiens lain untuk ID daftar pengguna 77778888, kirim kedua anggota audiens tersebut dalam satu permintaan dengan menetapkan reference setiap Destination. reference ditentukan pengguna—satu-satunya persyaratan adalah setiap Destination memiliki reference yang unik. Berikut daftar destinations yang diubah untuk permintaan:

  "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"
    }
  ]

Tetapkan destination_references setiap AudienceMember untuk mengirimkannya ke satu atau beberapa tujuan tertentu. Misalnya, berikut AudienceMember yang hanya untuk Destination pertama, sehingga daftar destination_references-nya hanya berisi reference dari Destination pertama:

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

Kolom destination_references adalah daftar, sehingga Anda dapat menentukan beberapa tujuan untuk anggota audiens. Jika Anda tidak menetapkan destination_references dari AudienceMember, Data Manager API akan mengirim anggota audiens ke semua tujuan dalam permintaan.

Langkah berikutnya

Sebelumnya
Ringkasan audiens