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.

Identificatori di risorse

Gli oggetti nell'API Google Ads vengono indirizzati utilizzando nomi di risorse strutturati e identificatori compositi.

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 relativa struttura, consulta l'interfaccia REST Nomi delle risorse.

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, un AdGroupAd ha il pattern del nome della risorsa customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Poiché il suo identificatore composito combina l'ID gruppo di annunci principale (ad_group.id) e l'ID annuncio sottostante (ad_group_ad.ad.id), anteponiamo l'ID gruppo di annunci all'ID annuncio:

• AdGroupId di 123 + ~ + AdId di 45678 = gruppo di annunci composito ID annuncio 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 OAuth 2.0 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 di autorizzazioni sufficienti. Un errore USER_PERMISSION_DENIED indica che l'utente autenticato potrebbe non avere accesso all'account cliente specificato nella richiesta. Se il tuo progetto Google Cloud è approvato solo per l'accesso Test e invii una richiesta che ha come target un account di produzione, l'API restituisce AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION nella versione 25 e successive (o AuthorizationError.ACTION_NOT_PERMITTED nella versione 24 e precedenti). Per informazioni dettagliate sulla gestione delle autorizzazioni, consulta l'articolo Livelli di accesso a Google Ads.

login-customer-id

Si tratta dell'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.

https://googleads.googleapis.com/v25/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 sull'immagine del profilo in alto a destra. Se non includi questa intestazione, per impostazione predefinita viene utilizzato il cliente operativo.

linked-customer-id

Questa intestazione è obbligatoria e viene utilizzata dai partner (ad esempio provider di analisi dati delle 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 contiene il collegamento al prodotto.

Considera lo scenario in cui un partner deve effettuare chiamate API a un account Google Ads in base a un link 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 prodotto stabilito con il partner, che concede a quest'ultimo l'accesso all'inserzionista.

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

Le intestazioni della richiesta devono essere impostate come segue:

• Authorization: un token di accesso OAuth 2.0 per un utente che ha accesso a Partner.
• login-customer-id: l'ID cliente dell'account 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'account Inserzionista ha un collegamento diretto al prodotto con l'account Partner, l'account collegato è l'Inserzionista e linked-customer-id deve essere impostato sull'ID cliente dell'account Inserzionista.
• Se l'account Inserzionista è gestito da un account amministratore che ha un collegamento prodotto con l'account 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'account inserzionista 1111111111 ha un collegamento diretto con l'account partner 2222222222 e la chiamata API ha come target customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Esempio 2: link del manager

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

Authorization: Bearer YOUR_ACCESS_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 a scopo di debug.

request-id

request-id è una stringa che identifica in modo univoco questa richiesta. Fornisci questo valore quando contatti l'assistenza per risolvere i problemi relativi alle richieste API non riuscite o impreviste.