Mengirim anggota audiens

Anda dapat mengikuti panduan memulai ini untuk memahami Data Manager API. Pilih versi panduan memulai 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 keberhasilan dan kegagalan.

Menyiapkan tujuan

Sebelum dapat mengirim data, Anda harus menyiapkan tujuan untuk mengirim data. Berikut adalah contoh Destination yang dapat Anda gunakan:

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • Tetapkan operatingAccount ke produk 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 maksimal 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, di akhir, dan di tengah.
  2. Konversi alamat email menjadi huruf kecil.
  3. Lakukan hashing 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 adalah 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 adalah 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 yang diformat, di-hash, dan dienkode dana@example.com dan danam@example.com dari baris pertama data input:

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

Membuat isi permintaan

Gabungkan Destination dan userData untuk isi permintaan:

{
  "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. Perbarui placeholder dalam isi, seperti OPERATING_ACCOUNT_PRODUCT, 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 sudah siap untuk menerapkan perubahan, tetapkan validateOnly ke false.
  3. Tetapkan termsOfService untuk menunjukkan bahwa pengguna telah menyetujui persyaratan layanan Match Pelanggan.
  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. Buka halaman audienceMembers.ingest.
  3. Klik tombol API di sebelah kanan, lalu tombol Coba di bagian yang diperluas.
  4. Tempelkan isi permintaan yang disalin ke kotak Isi permintaan.
  5. Klik tombol Execute, selesaikan perintah otorisasi, dan tinjau responsnya.

Respons sukses

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

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

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 heksadesimal 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]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Langkah berikutnya