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

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

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

เรียนรู้

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

วิธีการ SOAP เมธอด REST
getOrdersByStatement networks.orders.get
networks.orders.list

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

หากต้องการตรวจสอบสิทธิ์กับ Ad Manager API (เบต้า) คุณสามารถใช้ข้อมูลเข้าสู่ระบบ SOAP API ของ Ad Manager ที่มีอยู่หรือสร้างข้อมูลเข้าสู่ระบบใหม่ก็ได้ ไม่ว่าจะใช้ตัวเลือกใด คุณจะต้องเปิดใช้ 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: ข้อมูลลับของลูกค้าใหม่หรือลูกค้าเดิม

  • 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

    Ad Manager SOAP API PQL

    // 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" คุณใช้เครื่องหมายคำพูดเดี่ยวเพื่อตัดสตริงตัวอักษรล้วนไม่ได้

นำคำสั่งตามประโยคออก

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

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

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

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

Ad Manager API (เบต้า) ใช้พารามิเตอร์ pageSize เพื่อควบคุมขนาดหน้าเว็บ ซึ่งแตกต่างจากประโยค LIMIT ใน Ad Manager SOAP API ที่การละเว้นขนาดหน้าเว็บจะไม่แสดงชุดผลลัพธ์ทั้งหมด แต่เมธอดรายการจะใช้ขนาดหน้าเริ่มต้น 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 SOAP API เนื่องจาก Ad Manager 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