ส่งสมาชิกกลุ่มเป้าหมาย

คุณสามารถทำตามการเริ่มต้นอย่างรวดเร็วนี้เพื่อทำความคุ้นเคยกับ Data Manager API เลือกเวอร์ชันของคู่มือเริ่มต้นที่คุณต้องการดู

ในการเริ่มต้นอย่างรวดเร็วนี้ คุณจะได้ทำตามขั้นตอนต่อไปนี้

  1. เตรียม Destination เพื่อรับข้อมูลกลุ่มเป้าหมาย
  2. เตรียมข้อมูลกลุ่มเป้าหมายที่จะส่ง
  3. สร้างคำขอIngestionService สำหรับสมาชิกในกลุ่มเป้าหมาย
  4. ส่งคำขอด้วย Google APIs Explorer
  5. ทำความเข้าใจการตอบกลับที่สำเร็จและไม่สำเร็จ

เตรียมปลายทาง

ก่อนที่จะส่งข้อมูลได้ คุณต้องเตรียมปลายทางเพื่อส่งข้อมูลไปที่นั่น นี่คือตัวอย่าง Destination ที่คุณใช้ได้ ดูตัวอย่างปลายทางสำหรับสถานการณ์ต่างๆ ได้ที่กำหนดค่า ปลายทาง

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

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

      "productDestinationId": "AUDIENCE_ID"
    }
  • ตั้งค่า operatingAccount เป็นประเภทบัญชีและรหัสของบัญชีที่จะรับข้อมูลกลุ่มเป้าหมาย
  • หากข้อมูลเข้าสู่ระบบ OAuth เป็นของผู้ใช้ที่มีสิทธิ์เข้าถึงบัญชีดูแลจัดการ Google Ads ซึ่งมี operatingAccount เป็นหนึ่งในบัญชีย่อย ให้ตั้งค่า loginAccount เป็นประเภทบัญชีและรหัสของบัญชีดูแลจัดการ
  • หากข้อมูลเข้าสู่ระบบ 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,

อีเมลมีข้อกำหนดด้านการจัดรูปแบบและการแฮชดังนี้

  1. นำช่องว่างขึ้นต้น ต่อท้าย และระหว่างกลางออกทั้งหมด
  2. แปลงอีเมลเป็นตัวพิมพ์เล็ก
  3. แฮชอีเมลโดยใช้อัลกอริทึม SHA-256
  4. เข้ารหัสไบต์ของแฮชโดยใช้เลขฐานสิบหก (hex) หรือการเข้ารหัส Base64 ตัวอย่างในคำแนะนำนี้ใช้การเข้ารหัสฐานสิบหก

ข้อมูลที่จัดรูปแบบแล้วมีดังนี้

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

ต่อไปนี้คือตัวอย่าง AudienceMember สำหรับอีเมลที่จัดรูปแบบ แฮช และเข้ารหัส ของ dana@example.com และ danam@example.com จากแถวแรกของ ข้อมูลอินพุต

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

สร้างเนื้อหาคำขอ

รวม Destination และ userData สำหรับเนื้อหาคำขอ

{
  "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
}
  1. อัปเดตตัวยึดตำแหน่งในเนื้อหา เช่น OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID และ AUDIENCE_ID ด้วยค่าสำหรับบัญชีและปลายทาง
  2. ตั้งค่า validateOnly เป็น true เพื่อตรวจสอบคำขอโดยไม่ต้องใช้การเปลี่ยนแปลง เมื่อพร้อมที่จะใช้การเปลี่ยนแปลงแล้ว ให้ตั้งค่า validateOnly เป็น false
  3. ตั้งค่า termsOfService เพื่อระบุว่าผู้ใช้ยอมรับข้อกำหนดในการให้บริการของ การจับคู่ข้อมูลลูกค้าแล้ว
  4. โปรดทราบว่าคำขอนี้ระบุว่ามีการให้สิทธิ์ consent และไม่ได้ใช้ การเข้ารหัส

ส่งคำขอ

  1. คัดลอกเนื้อหาคำขอโดยใช้ปุ่มคัดลอกที่ด้านขวาบนของตัวอย่าง
  2. คลิกปุ่ม API ในแถบเครื่องมือ
  3. วางเนื้อความของคำขอที่คัดลอกมาลงในช่องเนื้อความของคำขอ
  4. คลิกปุ่มดำเนินการ ทำตามข้อความแจ้งการให้สิทธิ์ และตรวจสอบ การตอบกลับ

การตอบกลับที่สำเร็จ

คำขอที่สำเร็จจะแสดงการตอบกลับพร้อมออบเจ็กต์ที่มี requestId

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

บันทึก requestId ที่ส่งคืนเพื่อให้คุณเรียกข้อมูลการวินิจฉัย ได้เมื่อมีการประมวลผลปลายทางแต่ละแห่งในคำขอ

การตอบกลับที่ล้มเหลว

คำขอที่ไม่สำเร็จจะส่งผลให้รหัสสถานะการตอบกลับข้อผิดพลาด เช่น 400 Bad Request และการตอบกลับที่มีรายละเอียดข้อผิดพลาด

ตัวอย่างเช่น email_address ที่มีสตริงข้อความธรรมดาแทนค่าที่เข้ารหัสฐาน 16 จะสร้างการตอบกลับต่อไปนี้

{
  "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 ที่ไม่ได้แฮชและเข้ารหัสฐาน 16 เท่านั้นจะสร้างการตอบกลับต่อไปนี้ 

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

ส่งเหตุการณ์สำหรับปลายทางหลายแห่ง

หากข้อมูลมีสมาชิกในกลุ่มเป้าหมายสำหรับปลายทางต่างๆ คุณจะส่งข้อมูลเหล่านั้นในคำขอเดียวกันได้โดยใช้การอ้างอิงปลายทาง

เช่น หากคุณมีสมาชิกกลุ่มเป้าหมายสำหรับรหัสรายชื่อผู้ใช้ 11112222 และสมาชิกกลุ่มเป้าหมายอีกรายสำหรับรหัสรายชื่อผู้ใช้ 77778888 ให้ส่งสมาชิกกลุ่มเป้าหมายทั้ง 2 รายในคำขอเดียวโดยตั้งค่า reference ของแต่ละ Destination 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"
    }
  ]

ตั้งค่า destination_references ของ AudienceMember แต่ละรายการเพื่อส่งไปยังปลายทางที่เฉพาะเจาะจงอย่างน้อย 1 แห่ง ตัวอย่างเช่น AudienceMember ต่อไปนี้ใช้สำหรับ Destination แรกเท่านั้น ดังนั้นรายการ destination_references จึงมีเฉพาะ reference ของ Destination แรก

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

ฟิลด์ destination_references เป็นรายการ ดังนั้นคุณจึงระบุปลายทางหลายรายการสำหรับสมาชิกในกลุ่มเป้าหมายได้ หากคุณไม่ได้ตั้งค่า destination_referencesของ AudienceMember API ของ Data Manager จะส่ง สมาชิกกลุ่มเป้าหมายไปยังปลายทางทั้งหมดในคำขอ

ขั้นตอนถัดไป

ก่อนหน้า
ภาพรวมกลุ่มเป้าหมาย