การแมปช่อง

ใช้การแมปในตารางเพื่อแมปเมธอดและฟิลด์ของ Google Ads API กับเมธอดและฟิลด์ที่เทียบเท่าใน IngestEventsRequest ใน Data Manager API

การตรวจสอบสิทธิ์

Data Manager API ต้องใช้ข้อมูลเข้าสู่ระบบที่มีขอบเขตแตกต่างจาก Google Ads API ทำตามขั้นตอนในตั้งค่าการเข้าถึง API เพื่อสร้างข้อมูลเข้าสู่ระบบใหม่ที่มีขอบเขต Data Manager API

เมธอดของ API

Data Manager API ช่วยให้คุณอัปโหลดเหตุการณ์ยอดขายในร้านแต่ละชุดได้ใน IngestEventsRequest เดียว

ในทางตรงกันข้าม Google Ads API ต้องใช้กระบวนการ 3 ขั้นตอนโดยใช้ OfflineUserDataJobService ดังนี้

  1. สร้างงานโดยใช้ CreateOfflineUserDataJob
  2. เพิ่มการดำเนินการลงในงานโดยใช้ AddOfflineUserDataJobOperations
  3. เรียกใช้งานโดยใช้ RunOfflineUserDataJob

ช่องคำขอ

IngestEventsRequest แต่ละรายการจะขึ้นอยู่กับขีดจำกัดคำขอ หากจำนวนการดำเนินการในคำขอ AddOfflineUserDataJobOperations เกินขีดจำกัดเหล่านี้ คุณต้องแบ่งคำขอนี้ออกเป็นคำขอการนำเข้าข้อมูลของ Data Manager API หลายรายการ

ต่อไปนี้คือวิธีจับคู่ช่องของคำขอ Google Ads API กับ Data Manager API

CreateOfflineUserDataJobRequest

ตารางต่อไปนี้แสดงวิธีแมปช่องของ CreateOfflineUserDataJobRequest กับ IngestEventsRequest

CreateOfflineUserDataJobRequest (Google Ads API) IngestEventsRequest (Data Manager API) หมายเหตุ
customer_id destinations.operating_account ดูช่องลูกค้าและการกระทำที่ถือเป็น Conversion
  • ส่วนหัวของคำขอ developer-token
  • ส่วนหัวของคำขอ login-customer_id
  • ส่วนหัวของคำขอ linked-customer-id
 destinations ดูช่องลูกค้าและการกระทำที่ถือเป็น Conversion
  • job.status
  • job.failure_reason
 การวินิจฉัย ใช้ request_id ที่แสดงใน IngestEventsResponse เพื่อเรียกข้อมูลการวินิจฉัยเกี่ยวกับการอัปโหลด Conversion
job.id request_id ใช้ request_id ที่แสดงใน IngestEventsResponse เพื่อเรียกข้อมูลการวินิจฉัยเกี่ยวกับการอัปโหลด Conversion
job.external_id ไม่มีเวอร์ชันเทียบเท่า
job.type ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.third_party_metadata.partner_id destinations.login_account พาร์ทเนอร์ด้านข้อมูลที่อัปโหลด Conversion ยอดขายในร้านจะได้รับการระบุโดย login_account ของปลายทาง ดูรายละเอียดเพิ่มเติมได้ที่หัวข้อกำหนดค่าปลายทาง
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.third_party_metadata.partner_match_fraction ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.third_party_metadata.partner_upload_fraction ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.third_party_metadata.bridge_map_version_id ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.loyalty_fraction ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.transaction_upload_fraction ไม่มีเวอร์ชันเทียบเท่า
job.store_sales_metadata.custom_key
  • events[].custom_variables[].variable
  • events[].cart_data.items[].custom_variables[].variable
 แมปกับช่อง variable ของ CustomVariable ที่ระดับเหตุการณ์หรือ ItemCustomVariable ที่ระดับสินค้า
enable_match_rate_range_preview ไม่มีเวอร์ชันเทียบเท่า
validate_only validate_only
ไม่มีเวอร์ชันเทียบเท่า consent Google Ads API รองรับเฉพาะการระบุ consent ที่ระดับเหตุการณ์ใน UserData สำหรับ Data Manager API คุณสามารถระบุความยินยอมสำหรับเหตุการณ์ทั้งหมดในคำขอได้โดยตั้งค่าช่อง consent ใน IngestEventsRequest คุณสามารถลบล้างค่านี้สำหรับแต่ละเหตุการณ์ได้โดยตั้งค่าช่อง consent ของ Event
ไม่มีเวอร์ชันเทียบเท่า encoding ต้องระบุสำหรับการอัปโหลด UserData ตั้งค่าเป็น Encoding ที่ใช้สำหรับค่า UserIdentifier
ไม่มีเวอร์ชันเทียบเท่า encryption_info ตั้งค่าหากคำขอมีตัวระบุผู้ใช้ UserData ที่เข้ารหัส ดูรายละเอียดได้ที่การเข้ารหัส

AddOfflineUserDataJobOperationsRequest

ตารางต่อไปนี้แสดงวิธีแมปช่องของ AddOfflineUserDataJobOperationsRequest กับ IngestEventsRequest

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestEventsRequest (Data Manager API) หมายเหตุ
  • ส่วนหัวของคำขอ developer-token
  • ส่วนหัวของคำขอ login-customer_id
  • ส่วนหัวของคำขอ linked-customer-id
 destinations ดูช่องลูกค้าและการกระทำที่ถือเป็น Conversion
resource_name ไม่มีเวอร์ชันเทียบเท่า Data Manager API ไม่จำเป็นต้องอัปเดตทรัพยากรงาน
enable_partial_failure ไม่มีเวอร์ชันเทียบเท่า หาก IngestEventsRequest สำเร็จ ระบบจะจัดการความล้มเหลวที่เกิดขึ้นระหว่างการประมวลผลดาวน์สตรีมที่ระดับเหตุการณ์ ซึ่งอาจส่งผลให้สำเร็จบางส่วน ใช้การวินิจฉัยเพื่อเรียกดูสถานะการอัปโหลด รวมถึงข้อผิดพลาดและคำเตือนสำหรับแต่ละเหตุการณ์ หาก IngestEventsRequest ล้มเหลว (เช่น เนื่องจาก BadRequest) ระบบจะไม่ประมวลผลเหตุการณ์ใดๆ และคุณจะต้องแก้ไขข้อผิดพลาดแล้วลองส่งคำขออีกครั้ง ดูข้อมูลเพิ่มเติมได้ที่ทำความเข้าใจข้อผิดพลาดของ API
enable_warnings ไม่มีเวอร์ชันเทียบเท่า ใช้การวินิจฉัยเพื่อเรียกดูคำเตือนเกี่ยวกับคำขอ Data Manager API คุณไม่จำเป็นต้องเปิดใช้ตัวเลือกนี้
operations events การดำเนินการ OfflineUserDataJobOperation.create เทียบเท่ากับการส่ง IngestEventsRequest Data Manager API ไม่รองรับการนําเหตุการณ์ออก
validate_only validate_only
ไม่มีเวอร์ชันเทียบเท่า consent Google Ads API รองรับเฉพาะการระบุ consent ที่ระดับเหตุการณ์ใน UserData สำหรับ Data Manager API คุณสามารถระบุความยินยอมสำหรับเหตุการณ์ทั้งหมดในคำขอได้โดยตั้งค่าช่อง consent ใน IngestEventsRequest คุณสามารถลบล้างค่านี้สำหรับแต่ละเหตุการณ์ได้โดยตั้งค่าช่อง consent ของ Event
ไม่มีเวอร์ชันเทียบเท่า encoding ต้องระบุสำหรับการอัปโหลด UserData ตั้งค่าเป็น Encoding ที่ใช้สำหรับค่า UserIdentifier
ไม่มีเวอร์ชันเทียบเท่า encryption_info ตั้งค่าหากคำขอมีตัวระบุผู้ใช้ UserData ที่เข้ารหัส ดูรายละเอียดได้ที่การเข้ารหัส

ช่องลูกค้าและการกระทำที่ถือเป็น Conversion

Google Ads API ต้องใช้ส่วนหัวของคำขอ developer-token และคุณต้องตั้งค่าส่วนหัวของคำขอ login-customer-id และ linked-customer-id สำหรับสถานการณ์การตรวจสอบสิทธิ์ที่แตกต่างกัน

Data Manager API ไม่ต้องใช้โทเค็นของนักพัฒนาซอฟต์แวร์ และคุณระบุข้อมูลการเข้าสู่ระบบและข้อมูลลูกค้าที่ลิงก์โดยใช้ช่องของ Destination แทนส่วนหัวของคำขอ ดูข้อมูลเพิ่มเติมเกี่ยวกับปลายทางได้ที่กำหนดค่าปลายทาง

Google Ads API Destination (Data Manager API) หมายเหตุ
customer_idของคำขอ operating_account ตั้งค่า account_id เป็นรหัสลูกค้าของบัญชี Conversion ของ Google Ads ตั้งค่า account_type ของ operating_account เป็น GOOGLE_ADS
ส่วนหัวของคำขอ developer-token ไม่มีเวอร์ชันเทียบเท่า Data Manager API ไม่จำเป็นต้องใช้โทเค็นของนักพัฒนาซอฟต์แวร์
ส่วนหัวของคำขอ login-customer-id login_account ตั้งค่า account_id เป็นรหัสลูกค้าของบัญชีที่เข้าสู่ระบบ ตั้งค่า account_type เป็น GOOGLE_ADS หากบัญชีที่เข้าสู่ระบบเป็นบัญชี Google Ads หรือ DATA_PARTNER หากบัญชีที่เข้าสู่ระบบเป็นบัญชีพาร์ทเนอร์ด้านข้อมูล
ส่วนหัวของคำขอ linked-customer-id linked_account หากคุณเข้าถึง operating_account โดยใช้ลิงก์พาร์ทเนอร์ ให้ตั้งค่า account_id เป็นรหัสลูกค้าของบัญชีที่ลิงก์ และตั้งค่า account_type เป็น DATA_PARTNER มิเช่นนั้น อย่าตั้งค่าช่อง linked_account
conversion_action product_destination_id ตั้งค่าเป็นรหัสตัวเลขของการกระทำที่ถือเป็น Conversion อย่าใช้ชื่อทรัพยากร

ช่องข้อมูลของเหตุการณ์

ตารางต่อไปนี้แสดงวิธีที่ช่องของ Conversion ยอดขายในร้านแมประหว่าง API ทั้ง 2 รายการ

Data Manager API รองรับการรวมหลายรายการต่อเหตุการณ์ใน CartData ซึ่งแตกต่างจาก Google Ads API ที่รองรับการรวมเพียงรายการเดียวต่อธุรกรรมโดยใช้ ItemAttribute

OfflineUserDataJobOperation.create (Google Ads API) Event (Data Manager API) หมายเหตุ
ไม่มีเวอร์ชันเทียบเท่า event_source ต้องระบุ ตั้งค่าเป็น IN_STORE สำหรับ Conversion ยอดขายในร้าน
transaction_attribute.conversion_action destinations.product_destination_id ดูช่องลูกค้าและการกระทำที่ถือเป็น Conversion ใช้รหัสตัวเลขของการกระทำที่ถือเป็น Conversion แทนชื่อทรัพยากร
transaction_attribute.transaction_date_time event_timestamp
ดูรายละเอียดได้ที่รูปแบบการประทับเวลา
transaction_attribute.transaction_amount_micros
  • conversion_value (ต้องระบุ)
  • cart_data.items[].conversion_value
 ตั้งค่าเป็นค่าสกุลเงิน ไม่ใช่ค่าในหน่วยไมโคร เช่น สำหรับมูลค่า Conversion 150.23 บาท ให้ใช้ค่า 5.23
transaction_attribute.currency_code currency ต้องระบุ
transaction_attribute.order_id transaction_id ต้องระบุ
transaction_attribute.store_attribute.store_code event_location.store_id ต้องระบุ ตั้งค่ารหัสร้านค้าในช่อง store_id ในออบเจ็กต์ EventLocation
transaction_attribute.custom_value
  • custom_variables[].value
  • cart_data.items[].custom_variables[].value
 แมปกับช่อง value ของ CustomVariable ที่ระดับเหตุการณ์หรือ ItemCustomVariable ที่ระดับสินค้า
transaction_attribute.item_attribute.item_id cart_data.items[].merchant_product_id
transaction_attribute.item_attribute.merchant_id
  • cart_data.merchant_id
  • cart_data.items[].merchant_id
 หากตั้งค่า cart_data.merchant_id ระบบจะใช้ค่านี้เป็นค่าเริ่มต้นสำหรับสินค้าทั้งหมด แต่คุณสามารถลบล้างค่านี้สำหรับสินค้าแต่ละรายการได้
transaction_attribute.item_attribute.country_code
  • cart_data.merchant_feed_label
  • cart_data.items[].merchant_feed_label
 หากตั้งค่า cart_data.merchant_feed_label ระบบจะใช้ค่านี้เป็นค่าเริ่มต้นสำหรับสินค้าทั้งหมด แต่คุณสามารถลบล้างค่านี้สำหรับสินค้าแต่ละรายการได้
transaction_attribute.item_attribute.language_code
  • cart_data.merchant_feed_language_code
  • cart_data.items[].merchant_feed_language_code
 หากตั้งค่า cart_data.merchant_feed_language_code ระบบจะใช้ค่านี้เป็นค่าเริ่มต้นสำหรับสินค้าทั้งหมด แต่คุณสามารถลบล้างค่านี้สำหรับสินค้าแต่ละรายการได้
transaction_attribute.item_attribute.quantity cart_data.items[].quantity
ไม่มีเวอร์ชันเทียบเท่า cart_data.items[].unit_price ตั้งค่าเป็นราคาต่อหน่วย โดยไม่รวมภาษี ค่าจัดส่ง และส่วนลดที่กำหนดขอบเขตตามเหตุการณ์ (ระดับธุรกรรม) สำหรับสินค้านี้
user_identifiers
  • user_data.user_identifiers
  • third_party_user_data.user_identifiers
 ต้องระบุ

third_party_user_data ใช้โครงสร้างเดียวกับ user_data แต่ระบุว่าตัวระบุผู้ใช้มาจากแหล่งที่มาของบุคคลที่สาม ไม่ใช่ข้อมูลผู้ลงโฆษณาบุคคลที่หนึ่ง

ระบบจะอนุญาตให้ป้อนข้อมูล third_party_user_data เฉพาะในกรณีที่บัญชีที่เข้าสู่ระบบเป็นพาร์ทเนอร์ด้านข้อมูล (login_account.account_type เป็น DATA_PARTNER)

ดูรายละเอียดได้ที่ช่องตัวระบุผู้ใช้

consent consent API ทั้ง 2 รายการใช้ออบเจ็กต์ Consent ที่คล้ายกัน (ad_user_data, ad_personalization) สำหรับ Data Manager API คุณยังตั้งค่าความยินยอมสำหรับเหตุการณ์ทั้งหมดในคำขอได้ด้วยการตั้งค่าช่อง consent ใน IngestEventsRequest

ฟิลด์ตัวระบุผู้ใช้

UserIdentifier (Google Ads API) UserIdentifier (Data Manager API) หมายเหตุ
user_identifier_source

แหล่งที่มาจะเป็นตัวกำหนดฟิลด์ที่จะป้อนข้อมูลใน Event ของ Data Manager API ดังนี้

  • user_data
  • third_party_user_data

third_party_user_data ใช้โครงสร้างเดียวกับ user_data แต่ระบุว่าตัวระบุผู้ใช้มาจากแหล่งที่มาของบุคคลที่สาม ไม่ใช่ข้อมูลผู้ลงโฆษณาบุคคลที่หนึ่ง

ระบบจะอนุญาตให้ป้อนข้อมูล third_party_user_data เฉพาะในกรณีที่บัญชีที่เข้าสู่ระบบเป็นพาร์ทเนอร์ด้านข้อมูล (login_account.account_type เป็น DATA_PARTNER)

ดูรายละเอียดได้ที่ช่องตัวระบุผู้ใช้

hashed_email email_address ตั้งค่าเป็นอีเมลที่จัดรูปแบบและแฮชแล้ว นอกจากนี้ คุณยังเข้ารหัสอีเมลที่แฮชได้ด้วย
hashed_phone_number phone_number ตั้งค่าเป็นหมายเลขโทรศัพท์ที่จัดรูปแบบและแฮชแล้ว นอกจากนี้ คุณยังเข้ารหัสหมายเลขโทรศัพท์ที่แฮชได้ด้วย
address_info address ตั้งค่าเป็นออบเจ็กต์ AddressInfo ทำตามหลักเกณฑ์การจัดรูปแบบและการแฮช นอกจากนี้ คุณยังเข้ารหัสแอตทริบิวต์ที่แฮชของที่อยู่ได้ด้วย
address_info.hashed_first_name address.given_name
address_info.hashed_last_name address.family_name
address_info.country_code address.region_code
address_info.postal_code address.postal_code
address_info.city ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับปลายทาง Google Ads
address_info.state ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับปลายทาง Google Ads
address_info.hashed_street_address ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับปลายทาง Google Ads
ก่อนหน้า
ขั้นตอนในการอัปเกรด