ย้ายข้อมูลจาก 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 (เบต้า)

เรียนรู้

เมธอดบริการ SOAP API ของ Ad Manager มาตรฐานมีแนวคิดที่เทียบเท่ากันใน 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: 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

    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 (เบต้า) หากต้องการระบุลำดับการจัดเรียงสำหรับชุดผลลัพธ์ ให้นำคําสั่ง 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 แต่เมธอด 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 กำหนด ประเภทข้อมูลที่ระบุไว้ในDimension ค่า enum โปรดทราบว่าENUMมิติข้อมูลเป็นการแจงนับแบบเปิด คุณต้องจัดการค่า Enum ใหม่และที่ไม่รู้จักเมื่อแยกวิเคราะห์ผลลัพธ์

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

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