Eseguire la migrazione dall'API SOAP Ad Manager

L'API SOAP di Ad Manager è un'API legacy per leggere e scrivere i dati di Ad Manager ed eseguire report. Se puoi eseguire la migrazione, ti consigliamo di utilizzare l'API Ad Manager (beta). Tuttavia, le versioni dell'API SOAP di Ad Manager sono supportate per il loro ciclo di vita tipico. Per saperne di più, consulta la pianificazione del ritiro dell'API SOAP di Ad Manager.

La seguente guida illustra le differenze tra l'API SOAP di Ad Manager e l'API Ad Manager (beta).

Impara

I metodi di servizio dell'API SOAP di Ad Manager standard hanno concetti equivalenti nell'API Ad Manager. L'API Ad Manager dispone anche di metodi per leggere singole entità. La seguente tabella mostra un esempio di mapping per i metodi Order:

Metodo SOAP Metodi REST
getOrdersByStatement networks.orders.get
networks.orders.list

Autentica

Per l'autenticazione con l'API Ad Manager (beta), puoi utilizzare le credenziali dell'API Ad Manager SOAP esistenti o crearne di nuove. Con entrambe le opzioni, devi prima abilitare l'API Ad Manager nel tuo progetto Google Cloud. Per maggiori dettagli, vedi Autenticazione.

Se utilizzi una libreria client, configura le credenziali predefinite dell'applicazione impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave del service account. Per maggiori dettagli, vedi Come funzionano le credenziali predefinite dell'applicazione.

Se utilizzi le credenziali dell'applicazione installata, crea un file JSON nel seguente formato e imposta la variabile di ambiente sul relativo percorso:

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

Sostituisci i seguenti valori:

  • CLIENT_ID: il tuo ID client nuovo o esistente.
  • CLIENT_SECRET: il segreto client nuovo o esistente.

  • REFRESH_TOKEN: il token di aggiornamento nuovo o esistente.

Linux o macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Comprendere le differenze tra i filtri

Il linguaggio di query dell'API Ad Manager (beta) supporta tutte le funzionalità del linguaggio di query per i publisher (PQL), ma esistono differenze sintattiche significative.

Questo esempio per l'elenco degli oggetti Order illustra le modifiche principali, come la rimozione delle variabili di associazione, degli operatori sensibili alle maiuscole e minuscole e la sostituzione delle clausole ORDER BY e LIMIT con campi separati:

API SOAP di Ad Manager 

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

API Ad Manager (beta)

Formato JSON

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

Con codifica URL

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

L'API Ad Manager (beta) supporta tutte le funzionalità PQL, con le seguenti differenze di sintassi rispetto all'API SOAP di Ad Manager:

  • Gli operatori AND e OR fanno distinzione tra maiuscole e minuscole nell'API Ad Manager (beta). and e or in minuscolo vengono trattati come stringhe di ricerca letterali semplici, una funzionalità dell'API Ad Manager (beta) per eseguire ricerche nei campi.

    Utilizzare operatori in maiuscolo

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

    Minuscole considerate come letterali

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

  • Il carattere * è un carattere jolly per la corrispondenza delle stringhe. L'API Ad Manager (beta) non supporta l'operatore like.

    PQL dell'API SOAP di Ad Manager

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

    API Ad Manager (beta)

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

  • I nomi dei campi devono essere visualizzati a sinistra di un operatore di confronto:

    Filtro valido

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

    Filtro non valido

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

  • L'API Ad Manager (beta) non supporta le variabili di binding. Tutti i valori devono essere in linea.

  • I valori letterali stringa contenenti spazi devono essere racchiusi tra virgolette doppie, ad esempio "Foo bar". Non puoi utilizzare le virgolette singole per racchiudere i valori letterali di stringa.

Rimuovi le clausole di ordinamento

Specificare un ordine di ordinamento è facoltativo nell'API Ad Manager (beta). Se vuoi specificare un ordine di ordinamento per il set di risultati, rimuovi la clausola PQL ORDER BY e imposta il campo orderBy:

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

Eseguire la migrazione dagli offset ai token di impaginazione

L'API Ad Manager (beta) utilizza token di impaginazione anziché clausole LIMIT e OFFSET per scorrere grandi set di risultati.

L'API Ad Manager (beta) utilizza un parametro pageSize per controllare le dimensioni della pagina. A differenza della clausola LIMIT nell'API SOAP di Ad Manager, l'omissione di una dimensione della pagina non restituisce l'intero insieme di risultati. Il metodo di elenco utilizza invece una dimensione della pagina predefinita di 50. Il seguente esempio imposta pageSize e pageToken come parametri URL:

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

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

A differenza dell'API SOAP di Ad Manager, l'API Ad Manager (beta) potrebbe restituire meno risultati rispetto alle dimensioni della pagina richieste, anche se sono presenti pagine aggiuntive. Utilizza il campo nextPageToken per determinare se sono presenti altri risultati.

Sebbene non sia necessario un offset per la paginazione, puoi utilizzare il campo skip per il multithreading. Quando utilizzi il multithreading, utilizza il token di paginazione della prima pagina per assicurarti di leggere dallo stesso insieme di risultati:

# 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

Esegui la migrazione dei report

L'API SOAP può solo leggere ed eseguire report nello strumento Report ritirato. Al contrario, l'API REST può solo leggere, scrivere ed eseguire report interattivi.

Gli strumenti e le API di generazione dei report hanno uno spazio ID diverso. L'ID di un SavedQuery nell'API SOAP non può essere utilizzato nell'API REST.

Se utilizzi SavedQuery, puoi eseguire la migrazione del report a un report interattivo nell'interfaccia utente e creare una mappatura tra i due spazi ID. Per maggiori informazioni sulla migrazione dei report, consulta Eseguire la migrazione da Report a Report interattivi.

Comprendere le differenze tra le API

Esistono alcune differenze nel modo in cui le API SOAP e REST gestiscono le definizioni e i risultati dei report:

  • L'API SOAP aggiungeva automaticamente una dimensione ID corrispondente ai risultati quando un report richiedeva solo NAME. Nell'API REST, devi aggiungere esplicitamente la dimensione ID a ReportDefinition affinché venga inclusa nei risultati.

  • L'API SOAP non aveva tipi espliciti per le metriche. L'API REST definisce un tipo di dati, documentato sul valore enum Dimension. Tieni presente che le dimensioni ENUM sono enumerazioni aperte. Devi gestire i valori enum nuovi e sconosciuti durante l'analisi dei risultati.

  • L'API SOAP separava Dimensions e DimensionAttributes. L'API REST ha un'enumerazione Dimension unificata che contiene entrambi.

  • L'API SOAP non aveva un limite al numero di dimensioni. I report interattivi hanno un limite di 10 dimensioni sia nell'interfaccia utente che nell'API. Le dimensioni che sono suddivise in base allo stesso spazio ID vengono conteggiate come una singola dimensione. Ad esempio, includere solo ORDER_NAME, ORDER_ID e ORDER_START_DATE conta come una sola dimensione per il calcolo del limite.