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 sana. Berikut contoh Destination yang dapat Anda gunakan:

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • Tetapkan operatingAccount ke jenis akun dan ID akun yang akan menerima data audiens.

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

Gabungkan Destination dan userData untuk isi permintaan:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "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. Perbarui placeholder di isi, seperti OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID, dan AUDIENCE_ID dengan nilai untuk akun dan tujuan Anda.
  2. Tetapkan validateOnly ke true untuk memvalidasi permintaan tanpa menerapkan perubahan. Jika Anda sudah siap untuk menerapkan perubahan, tetapkan validateOnly ke false.
  3. Tetapkan termsOfService untuk menunjukkan bahwa pengguna telah menyetujui Persyaratan layanan Customer Match.
  4. Perhatikan bahwa permintaan ini menunjukkan bahwa consent diberikan, dan tidak menggunakan enkripsi.

Kirim permintaan

  1. Salin isi permintaan menggunakan tombol salin di kanan atas contoh.
  2. Klik tombol API di toolbar.
  3. Tempelkan isi permintaan yang disalin ke dalam kotak Isi permintaan.
  4. Klik tombol Execute, selesaikan perintah otorisasi, dan tinjau responsnya.

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

email_address 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 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 dari 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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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 mengirimkan anggota audiens ke semua tujuan dalam permintaan.

Langkah berikutnya

Sebelumnya
Ringkasan audiens