Ad Manager SOAP API'den geçiş

Ad Manager SOAP API, Ad Manager verilerinizi okumak ve yazmak ve rapor çalıştırmak için kullanılan eski bir API'dir. Taşıma yapabilecek durumdaysanız Ad Manager API'yi (Beta) kullanmanızı öneririz. Ancak Ad Manager SOAP API sürümleri, tipik yaşam döngüleri için desteklenir. Daha fazla bilgi için Ad Manager SOAP API Desteğinin sonlandırılması programı'na bakın.

Aşağıdaki kılavuzda, Ad Manager SOAP API ile Ad Manager API (Beta) arasındaki farklar özetlenmiştir.

Bilgi

Standart Ad Manager SOAP API hizmet yöntemlerinin Ad Manager API'de eşdeğer kavramları vardır. Ad Manager API'de tek varlıkları okumaya yönelik yöntemler de vardır. Aşağıdaki tabloda, Order yöntemleri için örnek bir eşleme gösterilmektedir:

SOAP yöntemi REST yöntemleri
getOrdersByStatement networks.orders.get
networks.orders.list

Kimliği doğrula

Ad Manager API (Beta) ile kimlik doğrulamak için mevcut Ad Manager SOAP API kimlik bilgilerinizi kullanabilir veya yeni kimlik bilgileri oluşturabilirsiniz. Her iki seçenekte de öncelikle Google Cloud projenizde Ad Manager API'yi etkinleştirmeniz gerekir. Daha fazla bilgi için Kimlik doğrulama başlıklı makaleyi inceleyin.

İstemci kitaplığı kullanıyorsanız GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini hizmet hesabı anahtar dosyanızın yoluna ayarlayarak uygulamanın varsayılan kimlik bilgilerini ayarlayın. Daha fazla bilgi için Uygulama Varsayılan Kimlik Bilgileri'nin işleyiş şekli başlıklı makaleyi inceleyin.

Yüklü Uygulama kimlik bilgilerini kullanıyorsanız aşağıdaki biçimde bir JSON dosyası oluşturun ve ortam değişkenini bunun yerine yoluna ayarlayın:

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

Aşağıdaki değerleri değiştirin:

  • CLIENT_ID: Yeni veya mevcut istemci kimliğiniz.
  • CLIENT_SECRET: Yeni veya mevcut müşteri gizli anahtarınız.

  • REFRESH_TOKEN: Yeni veya mevcut yenileme jetonunuz.

Linux veya macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Filtre farklılıklarını anlama

Ad Manager API (Beta) sorgu dili, tüm Yayıncı Sorgu Dili (PQL) özelliklerini destekler ancak önemli söz dizimi farklılıkları vardır.

Order nesnelerini listelemeyle ilgili bu örnekte, bağlama değişkenlerinin kaldırılması, büyük/küçük harf duyarlı operatörler ve ORDER BY ile LIMIT yan tümcelerinin ayrı alanlarla değiştirilmesi gibi önemli değişiklikler gösterilmektedir:

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)

JSON biçimi

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

URL kodlanmış

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), Ad Manager SOAP API'den aşağıdaki söz dizimi farklılıklarıyla birlikte tüm PQL özelliklerini destekler:

  • Ad Manager API (Beta)'de AND ve OR operatörleri büyük/küçük harfe duyarlıdır. Küçük and ve or, Ad Manager API'deki (Beta) bir özellik olan ve alanlarda arama yapmak için kullanılan salt gerçek arama dizeleri olarak değerlendirilir.

    Büyük harf operatörlerini kullanma

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

    Küçük harf, değişmez değer olarak değerlendirilir

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

  • * karakteri, dize eşleştirme için joker karakterdir. Ad Manager API (Beta), like operatörünü desteklemez.

    Ad Manager SOAP API PQL

    // 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_*"

  • Alan adları, karşılaştırma operatörünün sol tarafında görünmelidir:

    Geçerli filtre

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

    Geçersiz filtre

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

  • Ad Manager API (Beta), bağlama değişkenlerini desteklemez. Tüm değerler satır içine yerleştirilmelidir.

  • Boşluk içeren dize değişmezleri çift tırnak içine alınmalıdır (örneğin, "Foo bar"). Dize değişmezlerini sarmalamak için tek tırnak kullanamazsınız.

Sıralama ölçütü yan tümcelerini kaldırma

Ad Manager API'de (Beta) sıralama sırası belirtmek isteğe bağlıdır. Sonuç kümeniz için bir sıralama düzeni belirtmek istiyorsanız PQL ORDER BY yan tümcesini kaldırın ve bunun yerine orderBy alanını ayarlayın:

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

Ofsetlerden sayfalandırma jetonlarına geçiş

Ad Manager API (Beta), büyük sonuç kümelerinde sayfalandırma için LIMIT ve OFFSET yan tümceleri yerine sayfalandırma jetonları kullanır.

Ad Manager API (Beta), sayfa boyutunu kontrol etmek için pageSize parametresini kullanır. Ad Manager SOAP API'deki LIMIT yan tümcesinin aksine, bir sayfa boyutunun atlanması sonuç kümesinin tamamını döndürmez. Bunun yerine liste yöntemi, varsayılan olarak 50 sayfa boyutunu kullanır. Aşağıdaki örnekte, pageSize ve pageToken URL parametreleri olarak ayarlanmıştır:

# 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'den farklı olarak Ad Manager API (Beta), ek sayfalar olsa bile istenen sayfa boyutundan daha az sonuç döndürebilir. Başka sonuç olup olmadığını belirlemek için nextPageToken alanını kullanın.

Sayfalandırma için ofset gerekli olmasa da çoklu iş parçacığı için skip alanını kullanabilirsiniz. Çoklu iş parçacığı kullanırken aynı sonuç kümesinden okuduğunuzdan emin olmak için ilk sayfadaki sayfalandırma jetonunu kullanın:

# 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