In diesem Dokument erfahren Sie, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl von HTTP-Verbindungen für den Client zu reduzieren.
In diesem Dokument wird ausschließlich das Erstellen einer Batchanfrage durch Senden einer HTTP-Anfrage behandelt. Wenn Sie stattdessen eine Google-Clientbibliothek für die Batchanfrage verwenden, lesen Sie die Informationen in der Dokumentation der Clientbibliothek.
Übersicht
Jede HTTP-Verbindung, die der Client erstellt, führt zu einem bestimmten Overhead. Die Display- und Die Video 360 API unterstützt Batchanfragen, damit Ihr Client mehrere API-Aufrufe in einer einzelnen HTTP-Anfrage zusammenfassen kann.
Fallbeispiele für den Einsatz von Batchanfragen:
- Ressourcen von mehreren Werbetreibenden abrufen
- Mehrere Ressourcen gleichzeitig erstellen oder aktualisieren
- Bearbeiten des Targetings für mehrere Werbebuchungen
In jedem Fall können Sie, anstatt jeden Aufruf einzeln zu senden, mehrere Aufrufe in einer einzigen HTTP-Anfrage zusammenfassen. Alle internen Anfragen müssen an dieselbe Google API gesendet werden.
Jede Batchanfrage ist auf maximal 1.000 Aufrufe begrenzt. Bei einer höheren Anzahl an Aufrufen erstellen Sie mehrere Batchanfragen.
Hinweis: Das Batchsystem für die Display- und Die Video 360 API verwendet dieselbe Syntax wie das Batchverarbeitungssystem von OData, aber die Semantik unterscheidet sich.
Batchdetails
Eine Batchanfrage besteht aus mehreren, in einer HTTP-Anfrage zusammengefassten API-Aufrufen. Sie kann an den im Discovery-Dokument der API angegebenen batchPath gesendet werden. Der Standardpfad ist /batch/api_name/api_version. In diesem Abschnitt wird die Batchsyntax im Detail beschrieben. Anschließend finden Sie ein Beispiel.
Hinweis: Wenn n Anfragen zu einem Batch zusammengefasst sind, werden auch n Anfragen auf Ihr Nutzungskontingent angerechnet, nicht nur eine einzige Anfrage. Die Batchanfrage wird vor der Verarbeitung in eine Reihe von Anfragen aufgeteilt.
Format einer Batchanfrage
Eine Batchanfrage ist eine einzelne Standard-HTTP-Anfrage mit mehreren Video 360 API-Aufrufe mit dem Inhaltstyp multipart/mixed. Jeder Teil der HTTP-Hauptanfrage enthält eine verschachtelte HTTP-Anfrage.
Jeder Teil beginnt mit seinem eigenen HTTP-Header Content-Type: application/http. Er kann auch einen optionalen Content-ID-Header haben. Die Header der einzelnen Teile sollen jedoch nur den Anfang des Teils markieren. Sie sind von der verschachtelten Anfrage getrennt. Nachdem der Server die Batchanfrage in separate Anfragen aufgeteilt hat, werden die Header der einzelnen Teile ignoriert.
Der Text jedes Teils ist an sich eine vollständige HTTP-Anfrage mit eigenem Verb, eigener URL, eigenen Headern und eigenem Text. Die HTTP-Anfrage darf nur den Pfadteil der URL enthalten; vollständige URLs sind in Batchanfragen nicht zulässig.
Die HTTP-Header für die äußere Batchanfrage gelten für jede Anfrage in dem Batch, ausgenommen Content--Header wie Content-Type. Wenn Sie einen bestimmten HTTP-Header sowohl in der äußeren Anfrage als auch in einem individuellen Aufruf verwenden, überschreibt der Wert des individuellen Aufrufheaders den Wert des Headers der äußeren Stapelanfrage. Die Header für einen individuellen Aufruf gelten nur für diesen Aufruf.
Beispiel: Wenn Sie einen Autorisierungsheader für einen bestimmten Aufruf angeben, gilt dieser Header nur für diesen Aufruf. Wenn Sie einen Autorisierungsheader für die äußere Anfrage angeben, gilt dieser Header für alle einzelnen Aufrufe, es sei denn, diese überschreiben ihn mit eigenen Autorisierungsheadern.
Wenn der Server die Stapelanfrage empfängt, wendet er (nach Bedarf) die Abfrageparameter und Header der äußeren Anfrage für jeden Teil an, und behandelt jeden Teil dann so, als wäre er eine separate HTTP-Anfrage.
Antwort auf eine Batchanfrage
Die Antwort des Servers ist eine einzelne Standard-HTTP-Antwort mit einem Inhaltstyp multipart/mixed. Jeder Teil ist die Antwort auf eine der Anfragen in der Batchanfrage in derselben Reihenfolge wie die einzelnen Anfragen.
Wie die Teile in der Anfrage enthält jeder Antwortteil eine vollständige HTTP-Antwort, einschließlich Statuscode, Headern und Text. Wie auch bei den Teilen in der Anfrage ist jedem Antwortteil ein Content-Type-Header vorangestellt, der den Beginn des Teils markiert.
Wenn ein bestimmter Teil einer Anfrage einen Content-ID-Header enthielt, enthält der entsprechende Teil der Antwort einen übereinstimmenden Content-ID-Header, wobei dem ursprünglichen Wert der String response- vorangestellt ist, wie im folgenden Beispiel dargestellt.
Hinweis: Der Server kann die Aufrufe in beliebiger Reihenfolge ausführen. Die Aufrufe werden nicht unbedingt in der Reihenfolge ausgeführt, in der Sie sie angegeben haben. Wenn Sie sicherstellen möchten, dass zwei Aufrufe in einer bestimmten Reihenfolge ausgeführt werden, können Sie sie nicht in einer einzelnen Anfrage senden. Senden Sie stattdessen den ersten Aufruf für sich alleine und warten Sie auf die Antwort auf den ersten Aufruf, bevor Sie den zweiten Aufruf senden.
Beispiel
Im folgenden Beispiel sehen Sie, wie die Batchverarbeitung mit den Video 360 API
Beispiel-Batchanfrage
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--
Beispiel für eine Stapelantwort
Dies ist die Antwort auf die Beispielanfrage im vorherigen Abschnitt.
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--
Clientbibliotheken verwenden
Die folgenden Codebeispiele zeigen, wie Sie Batchanfragen mit der Methode Google APIs-Clientbibliotheken. Weitere Informationen finden Sie in den entsprechenden Kurzanleitungen. wie Sie die Bibliotheken installieren und einrichten.
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);