İstekleri Gruplama

Dikkat: Kullanıcıların Display & Video 360 API'ye erişmek için toplu istek kullanmasını önermiyoruz. Bunun yerine, tek bir istekle birden fazla işlem yapmak için toplu ve kaynak genelinde işlevler kullanmayı düşünün.

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

Bu doküman, özellikle HTTP isteği göndererek toplu istek göndermeyle ilgilidir. Bunun yerine toplu istek yapmak için bir Google istemci kitaplığı kullanıyorsanız istemci kitaplığının belgelerine bakın.

Genel Bakış

İstemcinizin kurduğu her HTTP bağlantısı belirli miktarda ek yük oluşturur. Display & Video 360 API, istemcinizin tek bir HTTP isteğine birden fazla API çağrısı eklemesine olanak tanımak için gruplandırmayı destekler.

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

• Birden fazla reklamverenin kaynaklarını alma
• Kaynakları toplu olarak oluşturma veya güncelleme.
• Birden fazla satır öğesinde hedeflemeyi düzenleme

Her durumda, her çağrıyı ayrı ayrı göndermek yerine tek bir HTTP isteğinde gruplandırabilirsiniz. Tüm iç istekler aynı Google API'ye gönderilmelidir.

Tek bir toplu istekte 1.000 çağrıyla sınırlandırılırsınız. Bundan daha fazla arama yapmanız gerekiyorsa birden fazla toplu istek kullanın.

Not: Display & Video 360 API'nin toplu sistemi, OData toplu işleme sistemiyle aynı söz dizimi kullanır ancak anlamları farklıdır.

Toplu işlem ayrıntıları

Toplu istek, tek bir HTTP isteğinde birleştirilen birden fazla API çağrısından oluşur. Bu istek, API keşif belgesinde belirtilen batchPath adresine gönderilebilir. Varsayılan yol /batch/api_name/api_version'tir. Bu bölümde toplu söz dizimi ayrıntılı olarak açıklanmaktadır. Ardından bir örnek verilmiştir.

Not: Birlikte gruplandırılmış n istek grubu, kullanım sınırınıza tek bir istek olarak değil, n istek olarak dahil edilir. Toplu istek, işleme alınmadan önce bir dizi isteğe ayrılır.

Toplu istek biçimi

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

Her bir parça kendi Content-Type: application/http HTTP başlığıyla başlar. İsteğe bağlı bir Content-ID başlığı da olabilir. Ancak bölüm üst bilgileri yalnızca bölümün başlangıcını işaretlemek içindir ve iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteği ayrı istekler halinde açtıktan sonra bölüm üst bilgileri yoksayılır.

Her bir parçanı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 bölümünü içermelidir. Toplu isteklerde tam URL'lere izin verilmez.

Content-Type gibi Content- üstbilgileri hariç olmak üzere dış toplu istek için HTTP üstbilgileri, toplu istekteki her istek için geçerlidir. Hem dış istek hem de tek bir çağrıda belirli bir HTTP üst bilgisi belirtirseniz tek bir çağrı üst bilgisinin değeri, dış toplu istek üst bilgisinin değerini geçersiz kılar. Bir aramanın üstbilgileri yalnızca o arama için geçerlidir.

Örneğin, belirli bir arama için bir Yetkilendirme üst bilgisi sağlarsanız bu üstbilgi yalnızca söz konusu arama için geçerli olur. Dış istek için bir Yetkilendirme üst bilgisi sağlarsanız bu üst bilgi, kendi Yetkilendirme üst bilgileriyle geçersiz kılınmadığı sürece tüm ayrı çağrılar için geçerli olur.

Sunucu, toplu isteği aldığında dış isteğinin sorgu parametrelerini ve üst bilgilerini (uygun olduğu şekilde) her bir parçaya uygular ve ardından her bir parçayı ayrı bir HTTP isteği gibi işler.

Toplu istek yanıtı

Sunucunun yanıtı, multipart/mixed içerik türüne sahip tek bir standart HTTP yanıtıdır. Her bölüm, toplu istekteki isteklerden birine verilen yanıttır ve isteklerle aynı sıradadır.

İstekteki parçalar gibi her yanıt parçası da durum kodu, üstbilgiler ve gövde dahil olmak üzere eksiksiz bir HTTP yanıtı içerir. İstekteki bölümler gibi, her yanıt bölümünün önünde bölümün başlangıcını işaretleyen bir Content-Type üstbilgisi bulunur.

İsteğin belirli bir bölümünde Content-ID başlığı varsa yanıtın ilgili bölümünde de eşleşen bir Content-ID başlığı bulunur. Bu başlıkta, orijinal değerin önünde response- dizesi yer alır (aşağıdaki örnekte gösterildiği gibi).

Not: Sunucu, çağrılarınızı herhangi bir sırada gerçekleştirebilir. Bu komutların belirttiğiniz sırayla yürütüleceğini varsaymayın. İki çağrının belirli bir sırada gerçekleşmesini istiyorsanız bunları tek bir istekle gönderemezsiniz. Bunun yerine, ilkini tek başına gönderin ve ikinciyi göndermeden önce ilk çağrıya verilen yanıtı bekleyin.

Örnek

Aşağıdaki örnekte, Display & Video 360 API ile toplu işlemlerin kullanımı gösterilmektedir.

Ö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:[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--

Örnek toplu yanıt

Bu, önceki bölümdeki örnek isteğe verilen yanıttı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:[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--

İstemci kitaplıklarını kullanma

Aşağıdaki kod örnekleri, Google API'leri istemci kitaplıklarını kullanarak toplu isteklerin nasıl yapılacağını gösterir. Kitaplıkların nasıl yükleneceği ve ayarlanacağı hakkında daha fazla bilgi için ilgili hızlı başlangıç kılavuzlarına bakın.

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