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

คุณสามารถทำตามการเริ่มต้นอย่างรวดเร็วนี้เพื่อทำความคุ้นเคยกับ 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"
      }
    ]
  }
}

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

หากต้องการสร้างเนื้อหาคำขอ ให้รวม destinations และ audienceMembers ตั้งค่าฟิลด์ encoding และเพิ่มฟิลด์คำขออื่นๆ ที่ต้องการรวม เช่น validateOnly และ consent

หากส่งสมาชิกในกลุ่มเป้าหมายสำหรับการจับคู่ข้อมูลลูกค้า ให้ตั้งค่า termsOfService เพื่อระบุ ว่าผู้ใช้ยอมรับข้อกำหนดในการให้บริการของการจับคู่ข้อมูลลูกค้าหรือไม่

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

ส่งคำขอ

  1. คลิกเปิดในโปรแกรมสำรวจ API เพื่อเปิดโปรแกรมสำรวจ API ในแท็บหรือหน้าต่างใหม่
  2. ในเนื้อหาคำขอใน API Explorer ให้นำสตริงแต่ละรายการที่ขึ้นต้นด้วย REPLACE_WITH เช่น REPLACE_WITH_OPERATING_ACCOUNT_TYPE ไปแทนที่ด้วยค่าที่เกี่ยวข้อง
  3. คลิกดำเนินการที่ด้านล่างของหน้าโปรแกรมสำรวจ API แล้วทำตามข้อความแจ้งการให้สิทธิ์เพื่อส่งคำขอ
  4. ตั้งค่า validateOnly เป็น true เพื่อตรวจสอบคำขอโดยไม่ใช้การเปลี่ยนแปลง เมื่อพร้อมที่จะใช้การเปลี่ยนแปลงแล้ว ให้ตั้งค่า validateOnly เป็น false

คำขอส่งผ่านข้อมูล

เปิดใน 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
}

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

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

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

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

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

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

ตัวอย่างเช่น emailAddress ที่มีสตริงข้อความธรรมดาแทนค่าที่เข้ารหัสฐาน 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"
          }
        ]
      }
    ]
  }
}

emailAddress ที่ไม่ได้แฮชและเข้ารหัสเลขฐาน 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 Data Manager API จะส่ง สมาชิกกลุ่มเป้าหมายไปยังปลายทางทั้งหมดในคำขอ

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

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