İstekleri Gruplama

Bu belgede, HTTP bağlantılarının sayısını azaltmak için API çağrılarının nasıl toplu olarak kullanılacağı gösterilmektedir anlatacağım.

Bu belge özellikle, HTTP isteği. Bunun yerine, toplu istek yapmak için bir Google istemci kitaplığı kullanıyorsanız istemci kitaplığının dokümanlarına bakın.

Genel Bakış

İstemcinizin yaptığı her HTTP bağlantısı belirli miktarda ek yük oluşturur. Ekran ve Video 360 API, istemcinizin tek bir HTTP isteğine birden fazla API çağrısı yerleştirmesine olanak tanımak için toplu işlemeyi destekler.

Gruplandırmayı kullanmak isteyebileceğiniz durumlara örnekler:

  • Birden fazla reklamverenden kaynak alınıyor.
  • Kaynakları toplu olarak oluşturma veya güncelleme.
  • Birden fazla satır öğesinde hedefleme düzenleniyor.

Bu durumda her çağrıyı ayrı ayrı göndermek yerine tek bir HTTP isteği olarak gruplandırabilirsiniz. Dahili isteklerin tümü aynı Google API'sine gitmelidir.

Tek bir toplu istekte en fazla 1.000 arama yapabilirsiniz. Bundan daha fazla çağrı yapmanız gerekiyorsa birden çok toplu istek kullanın.

Not: Display &Video 360 için toplu işlem sistemi Video 360 API, OData toplu işleme sistemiyle aynı söz dizimini kullanır ancak anlamları farklıdır.

Grup ayrıntıları

Toplu istek, API keşif dokümanında belirtilen batchPath öğesine gönderilebilecek bir HTTP isteğinde birleştirilen birden çok API çağrısından oluşur. Varsayılan yol /batch/api_name/api_version şeklindedir. Bu bölümde, toplu söz dizimi ayrıntılı bir şekilde açıklanmaktadır; Daha sonra, bir örnek verelim.

Not: Gruplandırılmış n istekleri, kullanım sınırınıza tek bir istek olarak değil n isteği olarak dahil edilir. Toplu istek, işlenmeden önce bir dizi isteğe ayrılır.

Toplu isteğin biçimi

Toplu istek, birden fazla Display &Video 360'ı içeren tek bir standart HTTP isteğidir multipart/mixed içerik türünü kullanan Video 360 API çağrıları. Bu ana HTTP isteğinde, parçaların her biri iç içe yerleştirilmiş bir HTTP isteği içerir.

Her bölüm kendi Content-Type: application/http HTTP başlığıyla başlar. Ayrıca isteğe bağlı bir Content-ID başlığı da olabilir. Ancak, bölüm başlıkları yalnızca bölümün başlangıcını belirtmek içindir; iç içe yerleştirilmiş istekten ayrıdır. Sunucu toplu isteği ayrı isteklere dönüştürdükten sonra parça başlıkları yoksayılır.

Her bir bölümün gövdesi, kendi yüklemi, URL'si, başlıkları ve gövdesi ile eksiksiz bir HTTP isteğidir. HTTP isteği yalnızca URL'nin yol kısmını içermelidir; Toplu isteklerde tam URL'lere izin verilmez.

Dış toplu isteğin HTTP üstbilgileri (Content-Type gibi Content- üst bilgileri hariç), gruptaki her istek için geçerlidir. Hem dış istekte hem de tek bir çağrıda belirli bir HTTP üstbilgisi belirtirseniz bağımsız çağrı başlığının değeri, dış toplu istek başlığının değerini geçersiz kılar. Tek bir aramanın üstbilgileri yalnızca söz konusu çağrı için geçerlidir.

Örneğin, belirli bir çağrı için bir Yetkilendirme üstbilgisi sağlarsanız bu başlık yalnızca o çağrıya uygulanır. Dış istek için bir Yetkilendirme başlığı sağlarsanız bu başlık, kendi Yetkilendirme başlıklarıyla geçersiz kılınmadığı sürece tüm bağımsız çağrılar için geçerli olur.

Sunucu toplu isteği aldığında, dış isteğin sorgu parametrelerini ve başlıklarını (uygun şekilde) her bölüme uygular ve daha sonra, her bir bölümü ayrı bir HTTP isteğiymiş gibi değerlendirir.

Toplu isteğe yanıt verme

Sunucunun yanıtı, multipart/mixed içerik türüne sahip tek bir standart HTTP yanıtı olur; her bölüm, isteklerle aynı sırayla toplu istekteki isteklerden birinin yanıtıdır.

İstekteki bölümlerde olduğu gibi, her yanıt bölümü de durum kodu, başlıklar ve gövde dahil olmak üzere eksiksiz bir HTTP yanıtı içerir. İstekteki bölümlerde olduğu gibi, her yanıt bölümünün önünde, bölümün başlangıcını işaret eden bir Content-Type başlığı bulunur.

İsteğin belirli bir bölümünde Content-ID başlığı varsa yanıtın karşılık gelen bölümü, aşağıdaki örnekte gösterildiği gibi, orijinal değerin önünde response- dizesi olacak şekilde eşleşen bir Content-ID başlığına sahiptir.

Not: Sunucu, aramalarınızı herhangi bir sırada gerçekleştirebilir. Öğelerin sizin belirttiğiniz sırayla yürütülmesine izin vermeyin. İki çağrının belirli bir sırada gerçekleşmesini istiyorsanız bunları tek bir istekte gönderemezsiniz. ilkini tek başına gönderin. İkincisini göndermeden önce ilk yanıtın verilmesini bekleyin.

Örnek

Aşağıdaki örnekte, Display &Video 360'taki Video 360 API.

Örnek toplu istek

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

Örnek toplu yanıt

Bu, önceki bölümde yer alan örnek isteğin yanıtıdır.

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

İstemci kitaplıklarını kullanma

Aşağıdaki kod örnekleri, Google API'leri istemci kitaplıkları. Daha fazla bilgi için ilgili hızlı başlangıç kılavuzlarına göz atın kitaplıkların nasıl yükleneceği ve kurulacağı hakkında bilgi edinin.

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