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 dovrai conoscere i dettagli della richiesta sottostante. Tuttavia, una certa conoscenza della struttura delle chiamate API può essere utile 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 un 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 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 dei nomi delle risorse. Queste stringhe fungono anche da URL quando si utilizza l'interfaccia REST. Per la loro struttura, consulta Nomi delle risorse dell'interfaccia REST.

Punto chiave: consulta la documentazione delle 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 costruito un ID composito per l'oggetto anteponendo l'ID del relativo elemento principale e una tilde (~).

Ad esempio, poiché l'ID di un annuncio del gruppo di annunci non è univoco a livello globale, anteponiamo l'ID dell'oggetto principale (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 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.

Se riscontri errori di autorizzazione, assicurati di utilizzare le credenziali corrette e di disporre delle 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 a 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 di token sviluppatore è ABcdeFGH93KL-NOPQ_STUv. Il token 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 accedi all'account cliente 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, viene generato un errore AuthorizationError.USER_PERMISSION_DENIED. Per ulteriori informazioni su questo tipo di errore , consulta Errori comuni.

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

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

L'impostazione di login-customer-id equivale a scegliere un account nell'interfaccia utente di Google Ads dopo aver eseguito l'accesso o aver fatto clic sull'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 CustomerService.ListAccessibleCustomers richiesta. 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 del prodotto.

Considera lo scenario in cui un partner deve effettuare chiamate API a un account Google Ads in base a un collegamento del 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 del percorso customerId (ad esempio, customers/1111111111/...) e in gRPC, questo è il campo customer_id nella richiesta.
• Partner: l'account partner (ad esempio, un fornitore di analisi di app di terze parti o un partner di dati).
• Account collegato: l'account Google Ads che ha un collegamento del prodotto stabilito con il partner, che concede al partner l'accesso all'inserzionista.

Un utente che ha accesso al partner effettua chiamate API per agire sulle entità dell'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 delle richieste devono essere impostate come segue:

• Authorization: un token OAuth2 per un utente che ha accesso al 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 del 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 che ha un collegamento del prodotto con il partner, l'account collegato è l'account amministratore e linked-customer-id deve essere impostato sull'ID cliente dell'amministratore.

Esempio 1: collegamento diretto

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

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

Esempio 2: collegamento amministratore

Se l'inserzionista 1111111111 è gestito dall'amministratore 3333333333, l'amministratore 3333333333 ha un collegamento con il partner 2222222222 e la chiamata API è destinata a 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 metadati finali gRPC) vengono restituite con il corpo della risposta. Ti consigliamo di registrare questi valori per il debug.

request-id

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