Struttura della chiamata API

Questa guida descrive la struttura comune di tutte le chiamate API.

Se utilizzi una libreria client per interagire con l'API, non devi conoscere i dettagli della richiesta sottostante. Tuttavia, alcune conoscenze sulla struttura delle chiamate API possono essere utili durante i test e il debug.

L'API Google Ads è un'API gRPC con binding REST. Ciò significa che esistono due modi per effettuare chiamate all'API.

Preferito:

1. Crea il corpo della richiesta come protocol buffer.

2. Invialo al server utilizzando HTTP/2.

3. Deserializza la risposta in un protocol buffer.

4. Interpreta i risultati.

La maggior parte della nostra documentazione descrive l'utilizzo di gRPC.

Facoltativo:

1. Crea il corpo della richiesta come oggetto JSON.

2. Invialo al server utilizzando HTTP 1.1.

3. Deserializza la risposta come oggetto JSON.

4. Interpreta i risultati.

Per ulteriori informazioni sull'utilizzo di REST, consulta la guida all'interfaccia REST.

Nota: questa guida descrive le intestazioni di struttura e trasporto comuni ai protocolli gRPC e REST.

Nomi delle risorse

La maggior parte degli oggetti nell'API è identificata dalle stringhe del nome della risorsa. Queste stringhe fungono anche da URL quando viene utilizzata l'interfaccia REST. Consulta la sezione Nomi delle risorse dell'interfaccia REST per la loro struttura.

Punto chiave :consulta la documentazione sulle risorse per tutte le risorse supportate e la relativa rappresentazione del percorso (resource_name). Lo stesso formato viene utilizzato per altri servizi.

ID compositi

Se l'ID di un oggetto non è univoco a livello globale, viene creato un ID composito per l'oggetto anteponendo l'ID principale e una tilde (~).

Ad esempio, poiché l'ID annuncio di un gruppo di annunci non è univoco a livello globale, anteponiamo l'ID dell'oggetto principale (il gruppo di annunci) per creare un ID composito univoco:

• AdGroupId di 123 + ~ + AdGroupAdId di 45678 = ID annuncio gruppo di annunci composito di 123~45678.

Intestazioni delle richieste

Queste sono le intestazioni HTTP (o i metadati grpc) che accompagnano il corpo della richiesta:

Autorizzazione

Devi includere un token di accesso OAuth2 nel formato Authorization: Bearer YOUR_ACCESS_TOKEN che identifica un account amministratore che agisce per conto di un cliente o un inserzionista che gestisce direttamente il proprio account. Le istruzioni per recuperare un token di accesso sono disponibili nella guida OAuth2. Un token di accesso è valido per un'ora dopo l'acquisizione; quando scade, aggiorna il token di accesso per recuperarne uno nuovo. Tieni presente che le nostre librerie client aggiornano automaticamente i token scaduti.

developer-token

Un token sviluppatore è una stringa di 22 caratteri che identifica in modo univoco uno sviluppatore dell'API Google Ads. Una stringa di token sviluppatore di esempio è ABcdeFGH93KL-NOPQ_STUv. Il token sviluppatore deve essere incluso nel modulo developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Questo è l'ID cliente del cliente autorizzato da utilizzare nella richiesta, senza trattini (-). Se l'accesso all'account cliente avviene tramite un account amministratore, questa intestazione è obbligatoria e deve essere impostata sull'ID cliente dell'account amministratore.

Termine chiave: il cliente operativo è l'ID cliente nel payload della richiesta. Ad esempio, il cliente operativo nella seguente richiesta CampaignBudgetService è 1234567890:

https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate

L'impostazione di login-customer-id equivale alla scelta di un account nell'interfaccia utente di Google Ads dopo aver eseguito l'accesso o aver fatto clic sulla tua immagine del profilo in alto a destra. Se non includi questa intestazione, per impostazione predefinita viene utilizzato il cliente operativo.

Nota :puoi recuperare l'elenco degli account accessibili direttamente con le tue credenziali OAuth inviando una richiesta CustomerService.ListAccessibleCustomers. login-customer-id non è obbligatorio per questo tipo di richiesta e non ha alcun effetto sull'elenco dei clienti restituito.

linked-customer-id

Questa intestazione viene utilizzata solo dai [provider di analisi dati delle app di terze parti durante il caricamento delle conversioni in un account Google Ads collegato.

Considera lo scenario in cui gli utenti dell'account A forniscono l'accesso in lettura e modifica alle proprie entità all'account B tramite un ThirdPartyAppAnalyticsLink. Una volta collegato, un utente dell'account B può effettuare chiamate API all'account A, soggetto alle autorizzazioni fornite dal collegamento. In questo caso, le autorizzazioni di chiamata API all'account A sono determinate dal collegamento di terze parti all'account B, anziché dalla relazione tra account amministratore e account cliente utilizzata in altre chiamate API.

Il provider di analisi dati delle app di terze parti effettua una chiamata API nel seguente modo:

• linked-customer-id: l'account di analisi dell'app di terze parti che carica i dati (account B).
• customer-id: l'account Google Ads a cui vengono caricati i dati (account A).
• Intestazione login-customer-id e Authorization: una combinazione di valori per identificare un utente che ha accesso all'account B.

Intestazioni della risposta

Le seguenti intestazioni (o grpc trailing-metadata) vengono restituite con il corpo della risposta. Ti consigliamo di registrare questi valori a scopo di debug.

request-id

request-id è una stringa che identifica in modo univoco questa richiesta.