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 Ad Manager SOAP API 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 Ad Manager SOAP API standar memiliki konsep yang setara di Ad Manager API. Ad Manager API juga memiliki metode untuk membaca satu entity. 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 yang 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 jalur file tersebut:

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

Ganti nilai berikut:

  • CLIENT_ID: ID klien baru atau yang sudah ada.
  • CLIENT_SECRET: Secret klien baru atau yang sudah 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 Publisher Query Language (PQL), tetapi ada perbedaan sintaksis yang signifikan.

Contoh untuk mencantumkan objek Order ini mengilustrasikan perubahan besar seperti penghapusan variabel terikat, 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 kosong, 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 dianggap 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 terikat. 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 membungkus literal string.

Menghapus klausa pengurutan

Menentukan 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 sebagai gantinya:

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 menelusuri kumpulan hasil yang besar.

Ad Manager API (Beta) menggunakan parameter pageSize untuk mengontrol ukuran halaman. Tidak seperti klausa LIMIT di Ad Manager SOAP API, tidak mencantumkan ukuran halaman tidak akan 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 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

Memigrasikan laporan

SOAP API hanya dapat membaca dan menjalankan laporan di alat Laporan yang tidak digunakan lagi. Sebaliknya, REST API hanya dapat membaca, menulis, dan menjalankan Laporan Interaktif.

Alat dan API pelaporan memiliki ruang ID yang berbeda. ID SavedQuery di SOAP API tidak dapat digunakan di REST API.

Jika menggunakan SavedQuery, Anda dapat memigrasikan laporan ke laporan Interaktif di UI dan membuat pemetaan antara dua ruang ID. Untuk informasi selengkapnya tentang memigrasikan laporan, lihat Memigrasikan laporan ke Laporan interaktif.

Memahami perbedaan API

Ada beberapa perbedaan dalam cara SOAP API dan REST API menangani definisi dan hasil laporan:

  • SOAP API otomatis menambahkan dimensi ID yang sesuai ke hasil saat laporan hanya meminta NAME. Di REST API, Anda harus menambahkan dimensi ID secara eksplisit ke ReportDefinition agar disertakan dalam hasil.

  • SOAP API tidak memiliki jenis eksplisit untuk metrik. REST API menentukan jenis data, yang didokumentasikan pada nilai enum Dimension. Perhatikan bahwa dimensi ENUM adalah enum terbuka. Anda harus menangani nilai enum baru dan tidak diketahui saat mengurai hasil.

  • SOAP API memisahkan Dimensions dan DimensionAttributes. REST API memiliki enum Dimension terpadu yang berisi keduanya.

  • SOAP API tidak memiliki batasan jumlah dimensi. Laporan Interaktif memiliki batas 10 dimensi di UI dan API. Dimensi yang dikelompokkan menurut ruang ID yang sama dihitung sebagai satu dimensi. Misalnya, menyertakan ORDER_NAME, ORDER_ID, dan ORDER_START_DATE hanya dihitung sebagai 1 dimensi saat menghitung batas.