Bermigrasi dari Ad Manager SOAP API

Ad Manager SOAP API adalah API lama untuk membaca dan menulis data Ad Manager serta menjalankan laporan. Jika Anda dapat melakukan migrasi, sebaiknya gunakan Ad Manager API (Beta). Namun, versi SOAP API Ad Manager didukung untuk siklus proses umumnya. Untuk mengetahui informasi selengkapnya, lihat Jadwal Penghentian Penggunaan Ad Manager SOAP API.

Panduan berikut menguraikan perbedaan antara Ad Manager SOAP API dan Ad Manager API (Beta).

Pelajari

Metode layanan SOAP API Ad Manager standar memiliki konsep yang setara di Ad Manager API. Ad Manager API juga memiliki metode untuk membaca entitas tunggal. Tabel berikut menunjukkan contoh pemetaan untuk metode Order:

Metode SOAP Metode REST
getOrdersByStatement networks.orders.get
networks.orders.list

Autentikasikan

Untuk mengautentikasi dengan Ad Manager API (Beta), Anda dapat menggunakan kredensial Ad Manager SOAP API yang ada atau membuat kredensial baru. Dengan salah satu opsi tersebut, Anda harus mengaktifkan Ad Manager API terlebih dahulu di project Google Cloud Anda. Untuk mengetahui detail selengkapnya, lihat Autentikasi.

Jika Anda menggunakan library klien, siapkan kredensial default aplikasi dengan menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file kunci akun layanan Anda. Untuk mengetahui detail selengkapnya, lihat Cara kerja Kredensial Default Aplikasi.

Jika Anda menggunakan kredensial Aplikasi Terinstal, buat file JSON dalam format berikut dan tetapkan variabel lingkungan ke jalurnya:

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

Ganti nilai berikut:

  • CLIENT_ID: Client ID baru atau yang sudah ada.
  • CLIENT_SECRET: Secret klien baru atau yang ada.

  • REFRESH_TOKEN: Token refresh baru atau yang sudah ada.

Linux atau macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Memahami perbedaan filter

Bahasa kueri Ad Manager API (Beta) mendukung semua fitur Bahasa Kueri Penayang (PQL), tetapi ada perbedaan sintaksis yang signifikan.

Contoh untuk mencantumkan objek Order ini mengilustrasikan perubahan besar seperti penghapusan variabel pengikatan, operator peka huruf besar/kecil, dan penggantian klausa ORDER BY dan LIMIT dengan kolom terpisah:

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 (Beta)

Format JSON

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

URL yang dienkode

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 (Beta) mendukung semua kemampuan PQL, dengan perbedaan sintaksis berikut dari Ad Manager SOAP API:

  • Operator AND dan OR peka huruf besar/kecil di Ad Manager API (Beta). and dan or huruf kecil diperlakukan sebagai string penelusuran literal sederhana, fitur di Ad Manager API (Beta) untuk menelusuri di seluruh kolom.

    Menggunakan operator huruf besar

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

    Huruf kecil diperlakukan sebagai literal

    // 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

  • Karakter * adalah karakter pengganti untuk pencocokan string. Ad Manager API (Beta) tidak mendukung operator like.

    PQL Ad Manager SOAP API

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

    Ad Manager API (Beta)

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

  • Nama kolom harus muncul di sisi kiri operator perbandingan:

    Filter yang valid

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

    Filter tidak valid

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

  • Ad Manager API (Beta) tidak mendukung variabel pengikatan. Semua nilai harus disisipkan.

  • Literal string yang berisi spasi harus diapit tanda kutip ganda, misalnya, "Foo bar". Anda tidak dapat menggunakan tanda petik tunggal untuk menggabungkan literal string.

Menghapus klausa urutan

Penentuan urutan pengurutan bersifat opsional di Ad Manager API (Beta). Jika Anda ingin menentukan urutan pengurutan untuk kumpulan hasil, hapus klausa ORDER BY PQL dan tetapkan kolom orderBy:

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

Bermigrasi dari offset ke token penomoran halaman

Ad Manager API (Beta) menggunakan token penomoran halaman, bukan klausa LIMIT dan OFFSET untuk penomoran halaman melalui kumpulan hasil yang besar.

Ad Manager API (Beta) menggunakan parameter pageSize untuk mengontrol ukuran halaman. Tidak seperti klausa LIMIT di Ad Manager SOAP API, menghapus ukuran halaman tidak menampilkan seluruh kumpulan hasil. Sebagai gantinya, metode daftar menggunakan ukuran halaman default 50. Contoh berikut menetapkan pageSize dan pageToken sebagai parameter URL:

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

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

Tidak seperti Ad Manager SOAP API, Ad Manager API (Beta) dapat menampilkan lebih sedikit hasil daripada ukuran halaman yang diminta meskipun ada halaman tambahan. Gunakan kolom nextPageToken untuk menentukan apakah ada hasil tambahan.

Meskipun offset tidak diperlukan untuk penomoran halaman, Anda dapat menggunakan kolom skip untuk multithreading. Saat menggunakan multithreading, gunakan token penomoran halaman dari halaman pertama untuk memastikan Anda membaca dari set hasil yang sama:

# 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