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

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

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

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

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

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

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • ตั้งค่า operatingAccount เป็นประเภทบัญชีและรหัสของบัญชีที่จะรับข้อมูลกลุ่มเป้าหมาย

เตรียมข้อมูลกลุ่มเป้าหมาย

ลองดูข้อมูลตัวอย่างต่อไปนี้ในไฟล์ที่คั่นด้วยคอมมา แต่ละบรรทัดในไฟล์ จะสอดคล้องกับสมาชิก 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"
      },

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

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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 จะส่ง สมาชิกกลุ่มเป้าหมายไปยังปลายทางทั้งหมดในคำขอ

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

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