Migracja z interfejsu SOAP Ad Managera

Interfejs SOAP Ad Managera to starsza wersja interfejsu API służąca do odczytu i zapisywania danych w Ad Managerze oraz do generowania raportów. Jeśli możesz przeprowadzić migrację, zalecamy użycie interfejsu Ad Managera w wersji beta. Interfejs SOAP API Ad Managera jest jednak obsługiwany w ramach typowego cyklu życia. Więcej informacji znajdziesz w Harmonogram wycofywania interfejsu SOAP Ad Managera.

W tym przewodniku opisujemy różnice między interfejsem SOAP Ad Managera a interfejsem API Ad Managera (wersja beta).

Edukacja

Standardowe metody usługi w interfejsie SOAP Ad Managera mają swoje odpowiedniki w interfejsie Ad Managera API. Interfejs Ad Manager API zawiera też metody do odczytu pojedynczych encji. Tabela poniżej zawiera przykładowe mapowanie metod Order:

Metoda SOAP Metody REST
getOrdersByStatement networks.orders.get
networks.orders.list

Uwierzytelnij

Aby uwierzytelnić się za pomocą interfejsu Ad Manager API (w wersji beta), możesz użyć dotychczasowych danych logowania do interfejsu SOAP Ad Managera lub utworzyć nowe. W przypadku obu opcji musisz najpierw włączyć interfejs Ad Manager API w projekcie Google Cloud. Więcej informacji znajdziesz w artykule Uwierzytelnianie.

Jeśli używasz biblioteki klienta, skonfiguruj domyślne dane logowania aplikacji, ustawiając zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę do pliku klucza konta usługi. Więcej informacji znajdziesz w artykule Jak działają domyślne dane logowania aplikacji.

Jeśli używasz danych logowania aplikacji zainstalowanej na urządzeniu, utwórz plik JSON w tym formacie i zamiast tego ustaw zmienną środowiskową na jego ścieżkę:

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

Zastąp te wartości:

  • CLIENT_ID: nowy lub dotychczasowy identyfikator klienta.
  • CLIENT_SECRET: nowy lub istniejący clientsecret.

  • REFRESH_TOKEN: nowy lub istniejący token odświeżania.

Linux lub macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Różnice między filtrami

Język zapytań interfejsu Ad Manager API (w wersji beta) obsługuje wszystkie funkcje języka Publisher Query Language (PQL), ale występują znaczne różnice w składni.

Ten przykład listowania obiektów Order pokazuje najważniejsze zmiany, takie jak usunięcie zmiennych wiązania, uwzględnienie wielkości liter w operatorach oraz zastąpienie klauzul ORDER BY i LIMIT osobnymi polami:

Interfejs SOAP API Ad Managera 

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

Interfejs API Ad Managera (wersja beta)

Format JSON

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

zakodowany w formacie adresu URL,

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

Interfejs Ad Manager API (w wersji beta) obsługuje wszystkie możliwości PQL, z tymi różnicami w składni w porównaniu z interfejsem SOAP Ad Managera:

  • W interfejsie Ad Manager API (w wersji beta) operatory AND i OR rozróżniają wielkość liter. Małe litery and i or są traktowane jako zwykłe ciągi znaków wyszukiwania, czyli funkcja w interfejsie Ad Manager API (w wersji beta) umożliwiająca wyszukiwanie w różnych polach.

    Używanie operatorów w wielkiej literze

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

    Małe litery traktowane jako literalne

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

  • Znak * to symbol wieloznaczny dopasowujący ciągi znaków. Interfejs Ad Manager API (wersja beta) nie obsługuje operatora like.

    Interfejs API SOAP Ad Managera PQL

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

    Ad Manager API (wersja beta)

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

  • Nazwy pól muszą znajdować się po lewej stronie operatora porównywania:

    Prawidłowy filtr

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

    Nieprawidłowy filtr

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

  • Interfejs Ad Manager API (w wersji beta) nie obsługuje zmiennych bind. Wszystkie wartości muszą być wstawione.

  • Ciągi znaków zawierające spacje muszą być ujęte w cudzysłowie, na przykład "Foo bar". Nie można otaczać ciągów znaków cudzysłowami pojedynczymi.

Usuwanie klauzul zamówienia według

W usłudze Ad Manager API (beta) określenie kolejności sortowania jest opcjonalne. Jeśli chcesz określić kolejność sortowania zbioru wyników, usuń klauzulę PQL ORDER BY i zamiast niej użyj pola orderBy:

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

Migracja z przesunięcia do tokenów podziału na strony

Interfejs Ad Manager API (wersja beta) używa tokenów podziału na strony zamiast klauzul LIMIT i OFFSET do podziału dużych zbiorów wyników na strony.

Interfejs Ad Manager API (w wersji beta) używa parametru pageSize do kontrolowania rozmiaru strony. W przeciwieństwie do klauzuli LIMIT w interfejsie SOAP Ad Managera pominięcie rozmiaru strony nie powoduje zwrócenia całego zbioru wyników. Zamiast tego metoda listy używa domyślnego rozmiaru strony 50. W tym przykładzie parametry pageSize i pageToken są ustawiane jako parametry adresu URL:

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

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

W odróżnieniu od interfejsu SOAP Ad Managera interfejs Ad Managera w wersji beta może zwracać mniej wyników niż określony rozmiar strony, nawet jeśli są dostępne dodatkowe strony. Aby sprawdzić, czy są dostępne dodatkowe wyniki, użyj pola nextPageToken.

Mimo że przesunięcie nie jest wymagane do podziału na strony, możesz użyć pola skip do wielowątkowości. W przypadku wielowątkowości użyj tokenu podziału na strony z pierwszej strony, aby mieć pewność, że odczytujesz dane z tego samego zbioru wyników:

# 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