Bu sayfa, Cloud Translation API ile çevrilmiştir.

İstekleri Gruplama

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

Bu belge özellikle bir HTTP isteği göndererek toplu istek oluşturmakla ilgilidir. 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 oluşturduğu her HTTP bağlantısı belirli bir miktarda ek yüke neden olur. Display & Video 360 API, istemcinizin tek bir HTTP isteğine birkaç API çağrısı koymasına olanak tanımak için toplu işlemi destekler.

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

Birden çok reklamverenden kaynaklar alınıyor.
Kaynakları toplu olarak oluşturma veya güncelleme.
Birden fazla satır öğesinde hedeflemeyi düzenleme.

Her durumda, her bir çağrıyı ayrı ayrı göndermek yerine bunları tek bir HTTP isteğinde gruplayabilirsiniz. Dahili istekler aynı Google API'ye yönlendirilmelidir.

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

Not: Display & Video 360 API'sinin toplu işlem sistemi, 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 belgesinde belirtilen batchPath öğesine gönderilebilen bir HTTP isteğinde birleştirilen birden fazla 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ı olarak açıklanmaktadır; daha sonra bir örnek vardır.

Not: Toplu olarak toplanan bir n istek kümesi, kullanım sınırınıza tek bir istek olarak değil, n istekleri olarak dahil edilir. Toplu istek, işlenmeden önce bir istek grubuna ayrılır.

Toplu isteğin 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 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 içerebilir. Bununla birlikte, parça başlıkları yalnızca bölümün başlangıcını işaretlemek için yer alır; iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteğin sarmalamasını ayrı istekler şeklinde açtıktan sonra parça başlıkları yok sayılır.

Her bölümün gövdesi, kendi yüklemi, URL'si, başlıkları ve gövdesi ile birlikte 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.

Content-Type gibi Content- üstbilgileri hariç olmak üzere dış toplu isteğin HTTP üstbilgileri, toplu işteki her isteğe uygulanır. Hem dış istekte hem de tek bir çağrıda belirli bir HTTP başlığı 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 arama için geçerlidir.

Örneğin, belirli bir çağrı için bir Yetkilendirme başlığı sağlarsanız bu üstbilgi yalnızca söz konusu çağrı için geçerli olur. Dış istek için bir Yetkilendirme üst bilgisi sağlarsanız bu başlık, kendi Yetkilendirme başlıklarıyla geçersiz kılınmadığı sürece tüm ç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 olduğu şekilde) her bir parçaya uygular ve ardından her bölümü ayrı bir HTTP isteğiymiş gibi ele alır.

Toplu isteğe yanıt verme

Sunucunun yanıtı, multipart/mixed içerik türüne sahip tek bir standart HTTP yanıtıdır. Her bir parça, isteklerle aynı sırayla toplu istekteki isteklerden birine verilen yanıttır.

İstekteki bölümler gibi, her yanıt bölümü de durum kodu, başlıklar ve gövdeyi içeren 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ı belirten bir Content-Type başlığı bulunur.

İsteğin belirli bir bölümünde Content-ID başlığı varsa yanıtın ilgili bölümü, aşağıdaki örnekte gösterildiği gibi önünde response- dizesinden önce gelen orijinal değer ile eşleşen bir Content-ID başlığına sahiptir.

Not: Sunucu, çağrılarınızı herhangi bir sırada gerçekleştirebilir. Bu kodların sizin belirttiğiniz sırayla yürütüldüğüne güvenin. Belirli bir sırada iki çağrının gerçekleşmesini istiyorsanız bunları tek bir istekte gönderemezsiniz. Bunun yerine, ilki tek başına gönderin, ardından ikinciyi göndermeden önce ilkinin yanıtını bekleyin.

Örnek

Aşağıdaki örnekte, Display & Video 360 API ile toplu işlemenin 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: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ı kullanılarak toplu isteklerin nasıl yapılacağını göstermektedir. Kitaplıkları yükleme ve ayarlama hakkında daha fazla bilgi için ilgili hızlı başlangıç kılavuzlarına göz atı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);