요청 일괄 처리

주의: 사용자가 일괄 요청을 사용하여 디스플레이 및 Video 360 API 대신 일괄 및 리소스 전체의 함수를 사용하면 단일 요청으로 여러 작업을 수행할 수 있습니다.

이 문서에서는 API 호출을 일괄 처리하여 클라이언트가 수행해야 하는 HTTP 연결 수를 줄이는 방법을 보여줍니다.

이 문서에서는 특히 HTTP 요청을 보내 일괄 요청을 하는 방법을 다룹니다. Google 클라이언트 라이브러리를 사용하여 일괄 요청을 하는 경우 클라이언트 라이브러리의 문서를 참조하세요.

개요

클라이언트가 수행하는 각 HTTP 연결에는 어느 정도의 오버헤드가 수반됩니다. 디스플레이 및 Video 360 API는 일괄 처리를 지원하므로 클라이언트에서 단일 HTTP 요청에 여러 API 호출을 넣을 수 있습니다.

다음과 같은 경우에 일괄 처리를 사용할 수 있습니다.

• 여러 광고주에서 리소스 검색
• 리소스 일괄 생성 또는 업데이트
• 여러 광고 항목에서 타겟팅을 수정하는 경우

각각의 경우 각 호출을 개별적으로 보내는 대신 단일 HTTP 요청으로 그룹화할 수 있습니다. 내부 요청은 모두 동일한 Google API로 이동해야 합니다.

일괄 요청 1개에 포함할 수 있는 호출 수는 1,000개로 제한됩니다. 더 많이 호출해야 하는 경우 일괄 요청을 여러 개 사용합니다.

참고: Display &Video 360용 일괄 처리 시스템 Video 360 API는 OData 일괄 처리 시스템과 동일한 구문을 사용하지만 시맨틱스는 다릅니다.

일괄 처리 세부정보

일괄 요청은 하나의 HTTP 요청으로 결합된 여러 API 호출로 구성되며, 이 요청을 API 탐색 문서에 지정된 batchPath로 보낼 수 있습니다. 기본 경로는 /batch/api_name/api_version입니다. 이 섹션에서는 일괄 처리 구문을 세부적으로 설명하며 뒷부분에서 예시를 제시합니다.

참고: 일괄 처리된 n개 요청의 사용량 한도를 계산할 때는 요청 하나가 아니라 n개로 계산됩니다. 일괄 요청은 일련의 요청 집합으로 분리된 후 처리됩니다.

일괄 요청의 형식

일괄 요청은 여러 개의 Display &Video 360 및 multipart/mixed 콘텐츠 유형을 사용하는 Video 360 API 호출 이 기본 HTTP 요청 내의 각 부분에 중첩된 HTTP 요청이 포함됩니다.

각 부분은 자체 Content-Type: application/http HTTP 헤더로 시작됩니다. 선택사항인 Content-ID 헤더가 있는 경우도 있습니다. 그러나 부분 헤더는 부분의 시작을 표시하기 위해 있을 뿐이며 중첩된 요청과는 별개입니다. 서버에서 일괄 요청을 개별 요청으로 해체하면 부분 헤더는 무시됩니다.

각 부분의 본문은 자체 동사와 URL, 헤더, 본문을 포함하는 완전한 HTTP 요청입니다. HTTP 요청은 URL의 경로 부분만 포함해야 합니다. 전체 URL은 일괄 요청에서 허용되지 않기 때문입니다.

외부 일괄 요청의 HTTP 헤더(Content-Type과 같은 Content- 헤더 제외)는 일괄 처리되는 각 요청에 모두 적용됩니다. 특정 HTTP 헤더를 외부 요청과 개별 호출에 모두 지정하는 경우 개별 호출 헤더의 값이 외부 일괄 요청 헤더의 값을 재정의합니다. 개별 호출의 헤더는 해당 호출에만 적용됩니다.

예를 들어 특정 호출에 승인 헤더를 제공하는 경우 이 헤더는 해당 호출에만 적용됩니다. 외부 요청에 승인 헤더를 제공하는 경우 이 헤더는 개별 호출에서 자체 승인 헤더로 재정의하지 않는 이상 모든 개별 호출에 적용됩니다.

서버는 일괄 요청을 수신하면 외부 요청의 쿼리 매개변수와 헤더를 각 부분에 적절히 적용한 다음 각 부분을 개별 HTTP 요청처럼 취급합니다.

일괄 요청 응답

서버 응답은 multipart/mixed 콘텐츠 유형의 단일 표준 HTTP 응답입니다. 각 부분은 일괄 요청에 포함된 요청 중 하나에 대한 응답이며 요청 순서와 동일한 순서로 표시됩니다.

요청의 부분과 마찬가지로 각 응답 부분에는 상태 코드, 헤더, 본문을 포함한 완전한 HTTP 응답이 포함됩니다. 또한 요청의 부분과 마찬가지로 각 응답 부분 앞에는 Content-Type 헤더가 붙어 부분의 시작을 표시합니다.

요청의 특정 부분에 Content-ID 헤더가 있는 경우 해당하는 응답 부분에도 일치하는 Content-ID 헤더가 표시되며 원래 값 앞에는 문자열 response-가 붙습니다(다음 예시 참조).

참고: 서버는 호출을 임의의 순서로 수행할 수 있습니다. 지정한 순서에 따라 실행된다고 생각하면 안 됩니다. 2개의 호출이 지정된 순서에 따라 실행되도록 하려면 1개의 요청으로 두 호출을 보내면 안 됩니다. 첫 번째 호출을 단독으로 보낸 다음 첫 번째 호출의 응답을 기다렸다가 두 번째 호출을 보내야 합니다.

예

다음 예는 Display &Video 360에서 일괄 처리를 Video 360 API

일괄 요청 예시

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:[e-mail]>

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:[e-mail]>

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

일괄 응답 예시

이전 섹션의 요청 예에 대한 응답입니다.

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:[e-mail]>

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:[e-mail]>

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

클라이언트 라이브러리 사용

다음 코드 샘플은 Google API 클라이언트 라이브러리 자세한 내용은 해당 빠른 시작 가이드를 참조하세요. 라이브러리를 설치하고 설정하는 방법에 대한 정보를 얻을 수 있습니다.

자바

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