การแมปช่อง

ใช้การแมปในตารางเพื่อแมปเมธอดและฟิลด์ 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 หรือ DATA_PARTNER หากบัญชีที่ใช้เข้าสู่ระบบเป็นบัญชีพาร์ทเนอร์ด้านข้อมูลGOOGLE_ADS
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 ที่ $5.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 ทั้ง 2 API ใช้ออบเจ็กต์ Consent ที่คล้ายกัน (ad_user_data, ad_personalization) สำหรับ Data Manager API คุณยังตั้งค่าความยินยอมสำหรับเหตุการณ์ทั้งหมดในคำขอได้ด้วยการตั้งค่าฟิลด์ consent ใน IngestEventsRequest

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

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

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

  • 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 ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับใน Data Manager API เวอร์ชันปัจจุบัน
address_info.state ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับใน Data Manager API เวอร์ชันปัจจุบัน
address_info.hashed_street_address ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับใน Data Manager API เวอร์ชันปัจจุบัน
ก่อนหน้า
ขั้นตอนในการอัปเกรด