Ad Manager SOAP API'den geçiş

Ad Manager SOAP API, Ad Manager verilerinizi okumak ve yazmak, ayrıca rapor çalıştırmak için kullanılan eski bir API'dir. Taşıma yapabiliyorsanız Ad Manager API'yi (Beta) kullanmanızı öneririz. Ancak Ad Manager SOAP API sürümleri, normal yaşam döngüleri boyunca desteklenir. Daha fazla bilgi için Ad Manager SOAP API Desteği Sonlandırma Takvimi'ne 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 hizmeti yöntemlerinin Ad Manager API'de eşdeğer kavramları vardır. Ad Manager API'sinde tek varlıkları okumak için de yöntemler bulunur. 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ğrulaması yapmak 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.

Bir istemci kitaplığı kullanıyorsanız GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini hizmet hesabı anahtar dosyanızın yoluna ayarlayarak varsayılan uygulama 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 yolu olarak 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 müşteri kimliğiniz.
  • CLIENT_SECRET: Yeni veya mevcut istemci 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 harfe duyarlı operatörler ve ORDER BY ile LIMIT ifadelerinin 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 kodlu

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:

  • AND ve OR operatörleri, Ad Manager API'de (Beta) büyük/küçük harfe duyarlıdır. Küçük harf and ve or, Ad Manager API'deki (Beta) alanlarda arama yapma özelliği olan yalın değişmez arama dizeleri olarak değerlendirilir.

    Büyük harfli operatörler kullanma

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

    Küçük harfler bire bir eşleşme 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'si (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çi olmalıdır.

  • 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 sarmak için tek tırnak kullanamazsınız.

Sıralama ölçütü ifadelerini kaldırma

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

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

Ötelemelerden sayfalama jetonlarına geçiş

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

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

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

Sayfalama için kaydırma gerekmemesine rağmen ç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 sayfalara ayı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

Raporları taşıma

SOAP API yalnızca kullanımdan kaldırılan Raporlar aracındaki raporları okuyabilir ve çalıştırabilir. Buna karşılık, REST API yalnızca etkileşimli raporları okuyabilir, yazabilir ve çalıştırabilir.

Raporlama araçları ve API'ler farklı bir kimlik alanına sahiptir. SOAP API'deki bir SavedQuery öğesinin kimliği, REST API'de kullanılamaz.

SavedQuery kullanıyorsanız raporu kullanıcı arayüzünde etkileşimli rapora taşıyabilir ve iki kimlik alanı arasında eşleme oluşturabilirsiniz. Raporları taşıma hakkında daha fazla bilgi için Raporları etkileşimli raporlara taşıma başlıklı makaleyi inceleyin.

API farklılıklarını anlama

SOAP API ve REST API'nin rapor tanımlarını ve sonuçlarını işleme şekli arasında bazı farklar vardır:

  • SOAP API, bir raporda yalnızca NAME istendiğinde sonuçlara otomatik olarak karşılık gelen bir ID boyutu ekliyordu. REST API'de, sonuçlara dahil edilmesi için ID boyutunu ReportDefinition öğesine açıkça eklemeniz gerekir.

  • SOAP API'de metrikler için açık türler yoktu. REST API, Dimension enum değerinde belgelenen bir veri türü tanımlar. ENUM boyutlarının açık numaralandırmalar olduğunu unutmayın. Sonuçları ayrıştırırken yeni ve bilinmeyen enum değerlerini işlemeniz gerekir.

  • SOAP API, Dimensions ve DimensionAttributes öğelerini ayırıyordu. REST API'de her ikisini de içeren birleştirilmiş bir Dimension enum'u bulunur.

  • SOAP API'de boyut sayısı sınırı yoktu. Etkileşimli raporlar hem kullanıcı arayüzünde hem de API'de 10 boyutla sınırlıdır. Aynı kimlik alanına göre ayrılan boyutlar tek bir boyut olarak sayılır. Örneğin, ORDER_NAME, ORDER_ID ve ORDER_START_DATE'nin dahil edilmesi, sınır hesaplanırken yalnızca 1 boyut olarak kabul edilir.