Questo documento mostra come raggruppare le chiamate API per ridurre il numero di connessioni HTTP che il client deve effettuare.
Questo documento riguarda nello specifico l'esecuzione di una richiesta batch tramite l'invio di una richiesta HTTP. Se invece utilizzi una libreria client di Google per effettuare una richiesta batch, consulta la documentazione della libreria client.
Panoramica
Ogni connessione HTTP che il tuo client genera comporta un certo overhead. L'API Display & Video 360 supporta il raggruppamento, per consentire al tuo client di inserire diverse chiamate API in una singola richiesta HTTP.
Esempi di situazioni in cui può essere utile creare gruppi:
- Recupero di risorse tra più inserzionisti.
- Creazione o aggiornamento di risorse in blocco.
- Modifica del targeting per più elementi pubblicitari.
In ogni caso, invece di inviare ogni chiamata separatamente, puoi raggrupparle in un'unica richiesta HTTP. Tutte le richieste interne devono essere indirizzate alla stessa API di Google.
Puoi effettuare un massimo di 1000 chiamate in una singola richiesta batch. Se devi effettuare un numero maggiore di chiamate, utilizza più richieste batch.
Nota: il sistema batch per l'API Display & Video 360 utilizza la stessa sintassi del sistema di elaborazione batch OData, ma la semantica è diversa.
Dettagli batch
Una richiesta batch è composta da più chiamate API combinate in un'unica richiesta HTTP, che può essere inviata al batchPath specificato nel documento di rilevamento API. Il percorso predefinito è /batch/api_name/api_version. In questa sezione viene descritta in dettaglio la sintassi batch; in seguito troverai un esempio.
Nota: un insieme di richieste n raggruppate insieme viene conteggiato come richiesta n, non come richiesta singola. La richiesta batch viene suddivisa in un insieme di richieste prima dell'elaborazione.
Formato di una richiesta batch
Una richiesta batch è una singola richiesta HTTP standard contenente più chiamate API Display & Video 360, che utilizzano il tipo di contenuti multipart/mixed. All'interno della richiesta HTTP principale, ciascuna delle parti contiene una richiesta HTTP nidificata.
Ogni parte inizia con la propria intestazione HTTP Content-Type: application/http. Può anche avere un'intestazione Content-ID facoltativa. Tuttavia, le intestazioni delle parti servono solo a contrassegnare l'inizio della parte e sono separate dalla richiesta nidificata. Una volta che il server ha annullato il wrapping della richiesta batch in richieste separate, le intestazioni delle parti vengono ignorate.
Il corpo di ogni parte è a sua volta una richiesta HTTP completa, con il proprio verbo, URL, intestazioni e corpo. La richiesta HTTP deve contenere solo la parte del percorso dell'URL; gli URL completi non sono consentiti nelle richieste batch.
Le intestazioni HTTP per la richiesta batch esterna, ad eccezione delle intestazioni Content- come Content-Type, si applicano a ogni richiesta del batch. Se specifichi una determinata intestazione HTTP sia nella richiesta esterna che in una singola chiamata, il valore dell'intestazione della singola chiamata sostituisce il valore dell'intestazione della richiesta batch esterna. Le intestazioni di una singola chiamata si applicano solo a quella chiamata.
Ad esempio, se fornisci un'intestazione Autorizzazione per una chiamata specifica, questa intestazione si applica solo a quella chiamata. Se fornisci un'intestazione Authorization per la richiesta esterna, questa si applica a tutte le singole chiamate, a meno che non la sostituisca con le intestazioni Authorization proprie.
Quando il server riceve la richiesta in batch, applica i parametri di query e le intestazioni della richiesta esterna (a seconda dei casi) a ciascuna parte, quindi tratta ogni parte come se fosse una richiesta HTTP separata.
Risposta a una richiesta batch
La risposta del server è una singola risposta HTTP standard con un tipo di contenuto multipart/mixed; ogni parte è la risposta a una delle richieste della richiesta in batch, nello stesso ordine delle richieste.
Come le parti della richiesta, ogni parte della risposta contiene una risposta HTTP completa, inclusi un codice di stato, intestazioni e corpo. E, come per le parti della richiesta, ogni parte della risposta è preceduta da un'intestazione Content-Type che segna l'inizio della parte.
Se una determinata parte della richiesta aveva un'intestazione Content-ID, la parte corrispondente della risposta avrà un'intestazione Content-ID corrispondente, con il valore originale preceduto dalla stringa response-, come mostrato nell'esempio seguente.
Nota: il server può effettuare le chiamate in qualsiasi ordine. Non considerare che vengano eseguite nell'ordine in cui li hai specificati. Se vuoi assicurarti che si verifichino due chiamate in un determinato ordine, non puoi inviarle in un'unica richiesta; invia la prima da sola, quindi attendi la risposta alla prima prima di inviare la seconda.
Esempio
L'esempio seguente mostra l'utilizzo del raggruppamento con l'API Display & Video 360.
Esempio di richiesta batch
POST /batch HTTP/1.1
Host: displayvideo.googleapis.com
Authorization: Bearer your_auth_code
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length
--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item1:12930812@displayvideo.example.com>
PATCH /v1/advertisers/advertiser_id?updateMask=displayName&fields=advertiserId,displayName HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_code
{
"displayName": "Updated Advertiser Name"
}
--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item2:12930812@displayvideo.example.com>
PATCH /v1/advertisers/advertiser_id/lineItems/line_item_id?updateMask=displayName&fields=lineItemId,displayName HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_code
{
"displayName": "Updated Line Item Name"
}
--batch_foobarbaz--
Esempio di risposta batch
Questa è la risposta alla richiesta di esempio nella sezione precedente.
HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@displayvideo.example.com>
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: response_part_1_content_length
{
"advertiserId": advertiser_id,
"displayName": "Updated Advertiser Name"
}
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@displayvideo.example.com>
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: response_part_2_content_length
{
"lineItemId": line_item_id,
"displayName": "Updated Line Item Name"
}
--batch_foobarbaz--
Utilizzo delle librerie client
I seguenti esempi di codice mostrano come effettuare richieste batch utilizzando le librerie client delle API di Google. Consulta le rispettive guide rapide per ulteriori informazioni su come installare e configurare le librerie.
Java
Long advertiserId = advertiser-id;
List<Long> lineItemIds = Arrays.asList(line-item-id-1, line-item-id-2);
BatchRequest batch = service.batch();
JsonBatchCallback<LineItem> callback = new JsonBatchCallback<LineItem>() {
public void onSuccess(LineItem lineItem, HttpHeaders responseHeaders) {
System.out.printf("Line Item '%s' is now active.\n",
lineItem.getName());
}
public void onFailure (GoogleJsonError error, HttpHeaders responseHeaders)
throws IOException{
System.out.printf("Error activating line item: %s\n", error.getMessage());
}
};
LineItem activatedLineItem = new LineItem().setEntityStatus("ENTITY_STATUS_ACTIVE");
for (Long lineItemId: lineItemIds) {
service.advertisers().lineItems().patch(advertiserId, lineItemId, activatedLineItem)
.setUpdateMask("entityStatus").queue(batch, callback);
}
batch.execute();Python
advertiser_id = advertiser-id
line_item_ids = [line-item-id-1, line-item-id-2]
def callback(request_id, response, exception):
if exception is not None:
print('Error activating line item "%s": %s' %
request_id, exception)
else:
print('Line item "%s" is now active.' %
response.get('name'))
batch = service.new_batch_http_request(callback=callback)
line_item_obj = {
'entityStatus': 'ENTITY_STATUS_ACTIVE'
}
for line_item_id in line_item_ids:
request = service.advertisers().lineItems().patch(
advertiserId=advertiser_id,
lineItemId=line_item_id,
updateMask="entityStatus",
body=line_item_obj
)
batch.add(request, request_id=line_item_id)
batch.execute()PHP
$advertiserId = advertiser-id;
$lineItemIds = array(line-item-id-1, line-item-id-2);
// Enable batching on client and create current batch
$service->getClient()->setUseBatch(true);
$batch = $service->createBatch();
// Create line item with updated fields
$updatedLineItem = new Google_Service_DisplayVideo_LineItem();
$updatedLineItem->setEntityStatus('ENTITY_STATUS_ACTIVE');
// Create request parameter array with update mask
$optParams = array('updateMask' => 'entityStatus');
// Add each patch request to the batch
foreach($lineItemIds as $lineItemId) {
$request = $this->service->advertisers_lineItems->patch(
$advertiserId,
$lineItemId,
$updatedLineItem,
$optParams
);
$requestId = $lineItemId;
$batch->add($request, $requestId);
}
// Execute batch request
$results = $batch->execute();
// Iterate through results
foreach($results as $responseId => $lineItem) {
$lineItemId = substr($responseId, strlen('response-') + 1);
if ($lineItem instanceof Google_Service_Exception) {
$e = $lineItem;
printf(
"Error activating line item '%s': %s\n",
$lineItemId,
$e->getMessage()
);
} else {
printf("Line item '%s' is now active.\n", $lineItem->getName());
}
}
$service->getClient()->setUseBatch(false);