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 della chiamata 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 buffer di protocollo.

2. Invialo al server utilizzando HTTP/2.

3. Deserializza la risposta in un buffer di protocollo.

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 saperne di più 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 si utilizza l'interfaccia REST. Per la struttura, consulta la sezione Nomi delle risorse dell'interfaccia REST.

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 padre (il gruppo di annunci) per creare un ID composito univoco:

• AdGroupId di 123 + ~ + AdGroupAdId di 45678 = ID annuncio del 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, aggiornalo per recuperarne uno nuovo. Tieni presente che le nostre librerie client aggiornano automaticamente i token scaduti.

Se si verificano errori di autorizzazione, assicurati di utilizzare le credenziali corrette e di disporre di autorizzazioni sufficienti. Un errore USER_PERMISSION_DENIED indica che l'utente autenticato potrebbe non avere accesso all'account cliente specificato nella richiesta. Per informazioni dettagliate sulla gestione delle autorizzazioni, consulta Livelli di accesso Google Ads.

developer-token

Un token sviluppatore è una stringa di 22 caratteri che identifica in modo univoco uno sviluppatore dell'API Google Ads. Un esempio di stringa del token sviluppatore è ABcdeFGH93KL-NOPQ_STUv. Il token dello sviluppatore deve essere incluso nel formato 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. Se non includi login-customer-id quando esegui l'autenticazione tramite un account amministratore, si verifica un errore AuthorizationError.USER_PERMISSION_DENIED. Per saperne di più su questo tipo di errore, consulta la sezione Errori comuni. Per una spiegazione dettagliata di come viene risolto l'accesso all'account, consulta la guida Modello di accesso OAuth.

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/v24/customers/1234567890/campaignBudgets:mutate

L'impostazione di login-customer-id equivale alla scelta di un account nell'interfaccia utente di Google Ads dopo l'accesso o al clic sull'immagine del profilo in alto a destra. Se non includi questa intestazione, viene impostato per impostazione predefinita 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 restituiti.

linked-customer-id

Questa intestazione è obbligatoria e viene utilizzata dai partner (ad esempio fornitori di analisi di app di terze parti o partner di dati) quando agiscono su un account Google Ads collegato. Questa intestazione deve specificare l'ID cliente dell'account Google Ads che ha il collegamento al prodotto.

Considera lo scenario in cui un partner deve effettuare chiamate API a un account Google Ads in base a un collegamento prodotto.

• Inserzionista: l'account Google Ads gestito o aggiornato dalla chiamata API. L'ID dell'account inserzionista è specificato nella richiesta. In REST, questo è il parametro di percorso customerId (ad esempio, customers/1111111111/...), mentre in gRPC è il campo customer_id nella richiesta.
• Partner: l'account partner (ad esempio, un fornitore di analisi delle app di terze parti o un partner di dati).
• Account collegato: l'account Google Ads che ha un collegamento dei prodotti stabilito con il partner, che concede a quest'ultimo l'accesso all'inserzionista.

Un utente che ha accesso a Partner effettua chiamate API per agire sulle entità in Inserzionista (ad esempio, per caricare le conversioni o gestire gli elenchi utenti). L'account collegato può essere l'inserzionista stesso o un account amministratore dell'inserzionista.

Le intestazioni della richiesta devono essere impostate come segue:

• Authorization: un token OAuth2 per un utente che ha accesso a Partner.
• developer-token: il token sviluppatore per l'applicazione API, in genere associato al partner.
• login-customer-id: l'ID cliente del partner. L'utente autenticato deve avere accesso a questo account.
• linked-customer-id: l'ID cliente dell'account collegato. Questa intestazione indica che l'autorizzazione per questa richiesta si basa sul collegamento del prodotto dell'account collegato con il partner.

Esistono due scenari di collegamento:

• Se l'inserzionista ha un collegamento diretto al prodotto con il partner, l'account collegato è l'inserzionista e linked-customer-id deve essere impostato sull'ID cliente dell'inserzionista.
• Se l'inserzionista è gestito da un account amministratore con un collegamento al prodotto con il partner, l'account collegato è l'account amministratore e linked-customer-id deve essere impostato sull'ID cliente dell'amministratore.

Esempio 1: link diretto

Se l'inserzionista 1111111111 ha un collegamento diretto con il partner 2222222222 e la chiamata API ha come target customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Esempio 2: link del manager

Se l'inserzionista 1111111111 è gestito dal gestore 3333333333, il gestore 3333333333 ha un collegamento con il partner 2222222222 e la chiamata API ha come target customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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.