Eseguire la migrazione dall'API SOAP Ad Manager

L'API SOAP di Ad Manager è un'API legacy per la lettura e la scrittura dei dati di Ad Manager e l'esecuzione di 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 standard dell'API SOAP di Ad Manager hanno concetti equivalenti nell'API Ad Manager. L'API Ad Manager include anche metodi per la lettura di singole entità. La seguente tabella mostra un esempio di mappatura per i metodi Order:

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

Autentica

Per eseguire l'autenticazione con l'API Ad Manager (beta), puoi utilizzare le credenziali dell'API SOAP di Ad Manager esistenti o crearne di nuove. In entrambi i casi, devi prima abilitare l' API Ad Manager nel tuo progetto Google Cloud. Per maggiori dettagli, consulta Autenticazione.

Se utilizzi una libreria client, configura le credenziali predefinite dell'applicazione impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file delle chiavi del service account. Per maggiori dettagli, consulta 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 tuo secret client nuovo o esistente.

  • REFRESH_TOKEN: il tuo 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 nell'uso dei filtri

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

Questo esempio per elencare gli oggetti Order illustra le modifiche principali, come la rimozione delle variabili di binding, gli operatori che fanno distinzione tra 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"
}

URL codificato

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 sintattiche rispetto all'API SOAP di Ad Manager:

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

    Utilizza operatori in maiuscolo

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

    Minuscole trattate 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 sul lato sinistro 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 stringa.

Rimuovere le clausole order by

La specifica di un ordinamento è facoltativa nell'API Ad Manager (beta). Se vuoi specificare un 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 paginazione

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

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 delle dimensioni della pagina non restituisce l'intero set di risultati. Il metodo list 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 altre pagine. Utilizza il campo nextPageToken per determinare se sono presenti altri risultati.

Sebbene un offset non sia obbligatorio per la paginazione, puoi utilizzare il campo skip per il multithreading. Quando utilizzi il multithreading, usa il token di paginazione della prima pagina per assicurarti di leggere dallo stesso set 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

Eseguire 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 reporting 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 saperne di più sulla migrazione dei report, consulta Eseguire la migrazione dei report a Report interattivi.

Comprendere le differenze tra le API

Esistono alcune differenze nel modo in cui l'API SOAP e l'API 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 il NAME. Nell'API REST, devi aggiungere esplicitamente la dimensione ID a ReportDefinition affinché sia inclusa nei risultati.

  • L'API SOAP non aveva tipi espliciti per le metriche. L'API REST definisce un tipo di dati, documentato sul Dimension valore di enumerazione. Tieni presente che le dimensioni ENUM sono enumerazioni aperte. Devi gestire i valori di enumerazione 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 sia nell'API. Le dimensioni che vengono suddivise in base allo stesso spazio ID vengono conteggiate come una singola dimensione. Ad esempio, l'inclusione di ORDER_NAME, ORDER_ID e ORDER_START_DATE conta come una sola dimensione nel calcolo del limite.