ย้ายข้อมูลจาก Ad Manager SOAP API

Ad Manager SOAP API เป็น API แบบเดิมสำหรับอ่านและเขียนข้อมูล Ad Manager รวมถึงเรียกใช้รายงาน เราขอแนะนำให้ใช้ Ad Manager API (เบต้า) หากคุณย้ายข้อมูลได้ อย่างไรก็ตาม ระบบจะรองรับ Ad Manager SOAP API เวอร์ชันต่างๆ ตามวงจรชีวิตปกติ ดูข้อมูลเพิ่มเติมได้ที่กำหนดการเลิกใช้งาน Ad Manager SOAP API

คู่มือต่อไปนี้จะสรุปความแตกต่างระหว่าง Ad Manager SOAP API กับ Ad Manager API (เบต้า)

เรียนรู้

เมธอดบริการ Ad Manager SOAP API มาตรฐานมีแนวคิดที่เทียบเท่าใน Ad Manager API นอกจากนี้ Ad Manager API ยังมีเมธอดสำหรับการอ่านเอนทิตีเดียวด้วย ตารางต่อไปนี้แสดงการแมปตัวอย่างสำหรับเมธอด Order

เมธอด SOAP เมธอด REST
getOrdersByStatement networks.orders.get
networks.orders.list

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

หากต้องการตรวจสอบสิทธิ์ด้วย Ad Manager API (เบต้า) คุณสามารถใช้ข้อมูลเข้าสู่ระบบ Ad Manager SOAP API ที่มีอยู่หรือสร้างข้อมูลเข้าสู่ระบบใหม่ก็ได้ ไม่ว่าคุณจะเลือกตัวเลือกใด คุณต้อง เปิดใช้ Ad Manager API ใน โปรเจ็กต์ Google Cloud ก่อน ดูรายละเอียดเพิ่มเติมได้ที่ การตรวจสอบสิทธิ์

หากคุณใช้ไลบรารีของไคลเอ็นต์ ให้ตั้งค่าข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชันโดยตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS เป็นเส้นทางของไฟล์คีย์บัญชีบริการ ดูรายละเอียดเพิ่มเติมได้ที่ วิธีทำงานของข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน

หากคุณใช้ข้อมูลเข้าสู่ระบบของแอปพลิเคชันที่ติดตั้ง ให้สร้างไฟล์ JSON ในรูปแบบต่อไปนี้ แล้วตั้งค่าตัวแปรสภาพแวดล้อมเป็นเส้นทางของไฟล์แทน

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

แทนที่ค่าต่อไปนี้

  • CLIENT_ID: รหัสไคลเอ็นต์ใหม่หรือที่มีอยู่
  • CLIENT_SECRET: Secret ของไคลเอ็นต์ใหม่หรือที่มีอยู่

  • REFRESH_TOKEN: โทเค็นเพื่อรีเฟรชใหม่หรือที่มีอยู่

Linux หรือ macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

ทำความเข้าใจความแตกต่างของตัวกรอง

ภาษาการค้นหาของ Ad Manager API (เบต้า) รองรับฟีเจอร์ทั้งหมดของ Publisher Query Language (PQL) แต่มีไวยากรณ์ที่แตกต่างกันอย่างมาก

ตัวอย่างนี้สำหรับการแสดงออบเจ็กต์ Order แสดงให้เห็นการเปลี่ยนแปลงที่สำคัญ เช่น การนำตัวแปรที่ผูกออก โอเปอเรเตอร์ที่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ และการแทนที่ข้อกำหนด ORDER BY และ LIMIT ด้วยช่องแยกกัน

Ad Manager SOAP API 

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

Ad Manager API (เบต้า)

รูปแบบ JSON

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

URL ที่เข้ารหัส

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

Ad Manager API (เบต้า) รองรับความสามารถทั้งหมดของ PQL โดยมีไวยากรณ์ที่แตกต่างจาก Ad Manager SOAP API ดังนี้

  • โอเปอเรเตอร์ AND และ OR จะ คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ใน Ad Manager API (เบต้า) and และ or ที่เป็นตัวพิมพ์เล็กจะถือว่าเป็นสตริงการค้นหาตามตัวอักษร ซึ่งเป็นฟีเจอร์ใน Ad Manager API (เบต้า) สำหรับการค้นหาในช่องต่างๆ

    ใช้โอเปอเรเตอร์ตัวพิมพ์ใหญ่

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    ตัวพิมพ์เล็กถือเป็นตัวอักษร

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false

  • อักขระ * เป็นไวลด์การ์ดสำหรับการจับคู่สตริง Ad Manager API (เบต้า) ไม่รองรับโอเปอเรเตอร์ like

    PQL ของ Ad Manager SOAP API

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    Ad Manager API (เบต้า)

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • ชื่อช่องต้องปรากฏทางด้านซ้ายของโอเปอเรเตอร์การเปรียบเทียบ

    ตัวกรองที่ถูกต้อง

    updateTime > "2024-01-01T00:00:00Z"

    ตัวกรองที่ไม่ถูกต้อง

    "2024-01-01T00:00:00Z" < updateTime

  • Ad Manager API (เบต้า) ไม่รองรับตัวแปรที่ผูก ค่าทั้งหมดต้องอยู่ในบรรทัด

  • ตัวอักษรสตริงที่มีช่องว่างต้องอยู่ในเครื่องหมายคำพูดคู่, เช่น "Foo bar" คุณจะใช้เครื่องหมายคำพูดเดี่ยวเพื่อครอบตัวอักษรสตริงไม่ได้

นำข้อกำหนด Order By ออก

การระบุลำดับการจัดเรียงเป็นตัวเลือกใน Ad Manager API (เบต้า) หากต้องการระบุลำดับการจัดเรียงสำหรับชุดผลลัพธ์ ให้นำข้อกำหนด PQL ORDER BY ออก แล้วตั้งค่าช่อง orderBy แทน

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

ย้ายข้อมูลจากออฟเซ็ตเป็นโทเค็นการแบ่งหน้า

Ad Manager API (เบต้า) ใช้โทเค็นการแบ่งหน้าแทนข้อกำหนด LIMIT และ OFFSET สำหรับการแบ่งหน้าผ่านชุดผลลัพธ์ขนาดใหญ่

Ad Manager API (เบต้า) ใช้พารามิเตอร์ pageSize เพื่อควบคุมขนาดหน้า การละเว้นขนาดหน้าจะ ไม่ แสดงชุดผลลัพธ์ทั้งหมด ซึ่งแตกต่างจากข้อกำหนด LIMIT ใน Ad Manager SOAP API แต่เมธอด List จะใช้ขนาดหน้าเริ่มต้นเป็น 50 ตัวอย่างต่อไปนี้ตั้งค่า pageSize และ pageToken เป็นพารามิเตอร์ของ URL

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

Ad Manager API (เบต้า) อาจแสดงผลลัพธ์น้อยกว่าขนาดหน้าที่ขอ แม้ว่าจะมีหน้าเพิ่มเติมก็ตาม ซึ่งแตกต่างจาก Ad Manager SOAP API ใช้ช่อง nextPageToken เพื่อดูว่ามีผลลัพธ์เพิ่มเติมหรือไม่

แม้ว่าการแบ่งหน้าจะไม่ต้องใช้ออฟเซ็ต แต่คุณก็ใช้ช่อง skip สำหรับการทำงานแบบมัลติเธรดได้ เมื่อทำงานแบบมัลติเธรด ให้ใช้โทเค็นการแบ่งหน้าจากหน้าแรกเพื่อให้แน่ใจว่าคุณกำลังอ่านจากชุดผลลัพธ์เดียวกัน

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50

ย้ายข้อมูลรายงาน

SOAP API อ่านและเรียกใช้รายงานได้เฉพาะในเครื่องมือรายงานที่เลิกใช้งานแล้วเท่านั้น ในทางกลับกัน REST API อ่าน เขียน และเรียกใช้รายงานแบบอินเทอร์แอกทีฟได้เท่านั้น

เครื่องมือและ API การรายงานมีพื้นที่รหัสที่แตกต่างกัน คุณไม่สามารถใช้รหัสของ SavedQuery ใน SOAP API ใน REST API ได้

หากคุณใช้ SavedQuery คุณสามารถย้ายข้อมูลรายงานไปยังรายงานแบบอินเทอร์แอกทีฟใน UI และสร้างการแมประหว่างพื้นที่รหัสทั้ง 2 ได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับการย้ายข้อมูลรายงานได้ที่ หัวข้อ การย้ายข้อมูลรายงานไปยังรายงานแบบอินเทอร์แอกทีฟ

ทำความเข้าใจความแตกต่างของ API

SOAP API และ REST API มีวิธีจัดการคำจำกัดความและผลลัพธ์ของรายงานที่แตกต่างกันดังนี้

  • SOAP API จะเพิ่มมิติข้อมูล ID ที่เกี่ยวข้องลงในผลลัพธ์โดยอัตโนมัติเมื่อรายงานขอเฉพาะ NAME ใน REST API คุณต้องเพิ่มมิติข้อมูล ID ลงใน ReportDefinition อย่างชัดเจนเพื่อให้รวมอยู่ในผลลัพธ์

  • SOAP API ไม่มีประเภทที่ชัดเจนสำหรับเมตริก REST API กำหนด ประเภทข้อมูลที่ระบุไว้ในค่า Enum Dimension โปรดทราบว่ามิติข้อมูล ENUM เป็น Enum แบบเปิด คุณต้องจัดการค่า Enum ใหม่และที่ไม่รู้จักเมื่อแยกวิเคราะห์ผลลัพธ์

  • SOAP API แยก Dimensions และ DimensionAttributes REST API มี Enum Dimension แบบรวมที่ประกอบด้วยทั้ง 2 อย่าง

  • SOAP API ไม่จำกัดจำนวนมิติข้อมูล รายงานแบบอินเทอร์แอกทีฟมีมิติข้อมูลได้สูงสุด 10 รายการ ทั้งใน UI และ API ระบบจะนับมิติข้อมูลที่แบ่งตามพื้นที่รหัสเดียวกันเป็นมิติข้อมูลเดียว เช่น การรวม ORDER_NAME, ORDER_ID และ ORDER_START_DATE จะนับเป็นมิติข้อมูลเดียวเมื่อคำนวณขีดจำกัด