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": {
        "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 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": {
        "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 di 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 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"
}

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

Langkah berikutnya

Sebelumnya
Ringkasan audiens