Żądania wsadowe

Ten dokument pokazuje, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń HTTP które musi osiągnąć klient.

W tym dokumencie omawiamy w szczególności wysyłanie żądania zbiorczego przez Żądanie HTTP. Jeśli zamiast tego do przesyłania zbiorczego używasz biblioteki klienta Google, zapoznaj się z dokumentacją biblioteki klienta.

Omówienie

Każde połączenie HTTP powoduje pewne narzuty. Wyświetlacz Interfejs Video 360 API obsługuje grupowanie, dzięki czemu klient może umieścić kilka wywołań interfejsu API w jednym żądaniu HTTP.

Przykłady sytuacji, w których warto używać grupowania:

Pobieram zasoby od wielu reklamodawców.
Zbiorcze tworzenie lub aktualizowanie zasobów.
Edytowanie kierowania wielu elementów zamówienia.

W każdym przypadku zamiast wysyłać każde wywołanie osobno, możesz je zgrupować w jedno żądanie HTTP. Wszystkie żądania wewnętrzne muszą trafiać do tego samego interfejsu API Google.

Jedno żądanie zbiorcze może zawierać maksymalnie 1000 wywołań. Jeśli musisz wykonać więcej wywołań, użyj wielu żądań zbiorczych.

Uwaga: system wsadowy dla reklam displayowych i Interfejs Video 360 API używa tej samej składni co system przetwarzania wsadowego OData, ale semantyka jest inna.

Szczegóły wsadu

Żądanie zbiorcze składa się z kilku wywołań interfejsu API połączonych w jedno żądanie HTTP, które może zostać wysłane do batchPath wskazanego w dokumencie na temat wykrywania interfejsów API. Ścieżka domyślna to /batch/api_name/api_version. W tej sekcji szczegółowo opisujemy składnię wsadu. oto przykład.

Uwaga: zbiór n zbiorczych żądań wlicza się do limitu wykorzystania jako żądania n, a nie jako jedno żądanie. Przed przetworzeniem żądanie zbiorcze jest dzielone na zestaw żądań.

Format żądania zbiorczego

Żądanie zbiorcze to pojedyncze standardowe żądanie HTTP zawierające wiele elementów typu Display & Wywołania interfejsu Video 360 API korzystające z typu treści multipart/mixed. Każda część tego głównego żądania HTTP zawiera zagnieżdżone żądanie HTTP.

Każda część zaczyna się od własnego nagłówka HTTP Content-Type: application/http. Może też mieć opcjonalny nagłówek Content-ID. Nagłówki części są jednak przeznaczone tylko do oznaczenia początku danej części, są niezależne od żądania zagnieżdżonego. Gdy serwer wyodrębni żądanie zbiorcze na osobne żądania, nagłówki części są ignorowane.

Treść każdej części to kompletne żądanie HTTP z własnym czasownikiem, adresem URL, nagłówkami i treścią. Żądanie HTTP może zawierać tylko ścieżkę adresu URL. w żądaniach zbiorczych nie można używać pełnych adresów URL.

Nagłówki HTTP zewnętrznego żądania zbiorczego, z wyjątkiem nagłówków Content-, takich jak Content-Type, mają zastosowanie do każdego żądania wsadu. Jeśli określony nagłówek HTTP określisz zarówno w żądaniu zewnętrznym, jak i w pojedynczym wywołaniu, wartość nagłówka tego wywołania zastąpi wartość zewnętrznego nagłówka żądania zbiorczego. Nagłówki pojedynczego połączenia odnoszą się tylko do tego połączenia.

Jeśli na przykład podasz nagłówek autoryzacji dla określonego wywołania, będzie on stosowany tylko do tego wywołania. Jeśli podasz nagłówek autoryzacji dla żądania zewnętrznego, będzie on stosowany do wszystkich poszczególnych wywołań, chyba że zastąpią go własnym nagłówkiem autoryzacji.

Po otrzymaniu żądania zbiorczego serwer stosuje do każdej części parametry zapytania i nagłówki żądania zewnętrznego (odpowiednio) do każdej części, a następnie traktuje każdą część jako osobne żądanie HTTP.

Odpowiedź na żądanie zbiorcze

Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP z typem treści multipart/mixed. każda część to odpowiedź na jedno z żądań w żądaniu zbiorczym, w tej samej kolejności co żądania.

Podobnie jak części żądania, każda odpowiedź zawiera pełną odpowiedź HTTP, w tym kod stanu, nagłówki i treść. Podobnie jak w przypadku części żądania, każda część odpowiedzi jest poprzedzona nagłówkiem Content-Type, który określa jej początek.

Jeśli dana część żądania miała nagłówek Content-ID, odpowiadająca jej część ma pasujący nagłówek Content-ID, w którym pierwotna wartość jest poprzedzona ciągiem response- (jak pokazano w przykładzie poniżej).

Uwaga: serwer może wykonywać połączenia w dowolnej kolejności. Nie licz na ich wykonanie w kolejności, w jakiej zostały one określone. Jeśli chcesz mieć pewność, że w danej kolejności będą wykonywane 2 wywołania, nie możesz ich wysłać w jednym żądaniu. wyślij pierwszy e-mail samodzielnie, a następnie zaczekaj, aż odpowiesz na pierwszy, przed wysłaniem kolejnego.

Przykład

Poniższy przykład pokazuje, jak grupować się za pomocą funkcji Display & Interfejs Video 360 API.

Przykładowe żądanie zbiorcze

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--

Przykładowa odpowiedź zbiorcza

To jest odpowiedź na przykładowe żądanie podane w poprzedniej sekcji.

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--

Korzystanie z bibliotek klienta

Poniżej znajdziesz przykładowy kod pokazujący, jak tworzyć żądania zbiorcze za pomocą interfejsu Biblioteki klienta interfejsów API Google. Więcej informacji znajdziesz w odpowiednich krótkich przewodnikach z informacjami o instalowaniu i konfigurowaniu bibliotek.

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);