बैचिंग अनुरोध

इस दस्तावेज़ में बताया गया है कि क्लाइंट के लिए बनाए जाने वाले एचटीटीपी कनेक्शन की संख्या कम करने के लिए, एपीआई कॉल को एक साथ कैसे बैच बनाना है.

यह दस्तावेज़, एचटीटीपी अनुरोध भेजकर बैच अनुरोध भेजने के बारे में है. इसके बजाय, अगर बैच अनुरोध करने के लिए Google क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो क्लाइंट लाइब्रेरी के दस्तावेज़ देखें.

खास जानकारी

आपका क्लाइंट हर एचटीटीपी कनेक्शन से, एक तय ओवरहेड के लिए नतीजे देता है. Display & Video 360 API पर एक साथ कई एपीआई कॉल करने की सुविधा काम करती है. इसकी मदद से आपका क्लाइंट एक ही एचटीटीपी अनुरोध में कई एपीआई कॉल कर सकता है.

उन स्थितियों के उदाहरण जब आपको एक साथ कई अनुरोध भेजने की ज़रूरत पड़ सकती है:

  • विज्ञापन देने वाली कई कंपनियों से संसाधन हासिल करना.
  • एक साथ कई संसाधन बनाना या अपडेट करना.
  • एक से ज़्यादा लाइन आइटम में टारगेटिंग में बदलाव करना.

हर मामले में, हर कॉल को अलग-अलग भेजने के बजाय, उन्हें एक ही एचटीटीपी अनुरोध में एक साथ ग्रुप किया जा सकता है. सभी आंतरिक अनुरोध एक ही Google API पर जाने चाहिए.

एक बार में ज़्यादा से ज़्यादा 1,000 कॉल किए जा सकते हैं. अगर आपको इससे ज़्यादा कॉल करने हैं, तो एक साथ कई अनुरोध करें.

ध्यान दें: Display & Video 360 API का बैच सिस्टम, OData बैच प्रोसेसिंग सिस्टम जैसे ही सिंटैक्स का इस्तेमाल करता है. हालांकि, सिमैंटिक अलग-अलग होते हैं.

बैच की जानकारी

एक साथ कई अनुरोध करने पर, एक ही एचटीटीपी अनुरोध में कई एपीआई कॉल शामिल होते हैं. इसे एपीआई डिस्कवरी दस्तावेज़ में दिए गए batchPath पर भेजा जा सकता है. डिफ़ॉल्ट पाथ /batch/api_name/api_version है. इस सेक्शन में बैच सिंटैक्स के बारे में पूरी जानकारी दी गई है. बाद में, इसका एक उदाहरण दिया गया है.

ध्यान दें: एक साथ बैच में भेजे गए n अनुरोधों के सेट को, इस्तेमाल करने की सीमा के तौर पर n अनुरोधों के तौर पर गिना जाता है, न कि एक अनुरोध के तौर पर. प्रोसेस किए जाने से पहले, एक साथ कई अनुरोधों को अलग करके, अनुरोधों के एक सेट में रखा जाता है.

बैच अनुरोध का फ़ॉर्मैट

कई अनुरोधों वाला अनुरोध, एक स्टैंडर्ड एचटीटीपी अनुरोध होता है. इसमें multipart/mixed कॉन्टेंट टाइप का इस्तेमाल करके, कई Display & Video 360 API कॉल शामिल होते हैं. उस मुख्य एचटीटीपी अनुरोध में, हर हिस्से में एक नेस्ट किया गया एचटीटीपी अनुरोध होता है.

हर हिस्सा अपने Content-Type: application/http एचटीटीपी हेडर से शुरू होता है. इसमें एक वैकल्पिक Content-ID हेडर भी हो सकता है. हालांकि, पार्ट हेडर सिर्फ़ हिस्से की शुरुआत को मार्क करने के लिए होते हैं; वे नेस्ट किए गए अनुरोध से अलग होते हैं. जब सर्वर बैच अनुरोध को अलग-अलग अनुरोधों में रैप कर देता है, तो पार्ट हेडर को अनदेखा कर दिया जाता है.

हर हिस्से का मुख्य हिस्सा अपने-आप में एक पूरा एचटीटीपी अनुरोध होता है. इसका अपना वर्ब, यूआरएल, हेडर, और मुख्य हिस्सा होता है. एचटीटीपी अनुरोध में सिर्फ़ यूआरएल का पाथ शामिल होना चाहिए; बैच अनुरोधों में पूरे यूआरएल की अनुमति नहीं है.

Content-Type जैसे Content- हेडर को छोड़कर, आउटर बैच अनुरोध के एचटीटीपी हेडर बैच के हर अनुरोध पर लागू होते हैं. अगर किसी एचटीटीपी हेडर को आउटर अनुरोध और किसी एक कॉल में तय किया जाता है, तो आउटर बैच अनुरोध के हेडर की वैल्यू को अलग-अलग कॉल हेडर की वैल्यू के तौर पर बदल दिया जाता है. किसी एक कॉल के हेडर सिर्फ़ उस कॉल पर लागू होते हैं.

उदाहरण के लिए, अगर आप किसी खास कॉल के लिए 'ऑथराइज़ेशन हेडर' देते हैं, तो वह हेडर सिर्फ़ उस कॉल पर लागू होता है. अगर आप आउटर अनुरोध के लिए ऑथराइज़ेशन हेडर देते हैं, तो वह हेडर सभी अलग-अलग कॉल पर तब तक लागू होता है, जब तक वे इसे अपने खुद के ऑथराइज़ेशन हेडर से नहीं बदलते.

जब सर्वर को बैच किया गया अनुरोध मिलता है, तो वह हर हिस्से पर आउटर अनुरोध के क्वेरी पैरामीटर और हेडर (ज़रूरत के मुताबिक) लागू करता है. इसके बाद, वह हर हिस्से को एक अलग एचटीटीपी अनुरोध की तरह मानता है.

बैच में किए गए अनुरोध का जवाब

सर्वर से मिलने वाला रिस्पॉन्स, multipart/mixed कॉन्टेंट टाइप वाला एक स्टैंडर्ड एचटीटीपी रिस्पॉन्स होता है. हर हिस्सा, बैच में भेजे गए अनुरोध में से किसी एक अनुरोध का जवाब होता है. यह रिस्पॉन्स के क्रम में दिया जाता है.

अनुरोध के हिस्सों की तरह, रिस्पॉन्स के हर हिस्से में पूरा एचटीटीपी रिस्पॉन्स होता है. इसमें स्टेटस कोड, हेडर, और मुख्य हिस्सा शामिल है. अनुरोध के हिस्सों की तरह, रिस्पॉन्स वाले हर हिस्से से पहले एक Content-Type हेडर होता है. यह हेडर, हिस्से की शुरुआत को मार्क करता है.

अगर अनुरोध के किसी दिए गए हिस्से में Content-ID हेडर था, तो रिस्पॉन्स के इससे मिलते-जुलते Content-ID हेडर का इस्तेमाल किया जाएगा. साथ ही, मूल वैल्यू से पहले स्ट्रिंग response- होगी, जैसा कि यहां दिए गए उदाहरण में दिखाया गया है.

ध्यान दें: सर्वर आपके कॉल किसी भी क्रम में कर सकता है. उसी क्रम में उनके एक्ज़ीक्यूट होने पर भरोसा न करें जिसमें आपने उन्हें तय किया था. अगर आपको यह पक्का करना है कि किसी दिए गए क्रम में दो कॉल आएं, तो उन्हें एक ही अनुरोध में नहीं भेजा जा सकता. इसके बजाय, पहला कॉल खुद ही भेजें. इसके बाद, दूसरे कॉल के जवाब का इंतज़ार करें.

उदाहरण

नीचे दिए गए उदाहरण में Display & 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: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--

बैच में दिए गए जवाब का उदाहरण

यह पिछले सेक्शन में उदाहरण के तौर पर दिए गए अनुरोध का जवाब है.

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

क्लाइंट लाइब्रेरी का इस्तेमाल करना

नीचे दिए गए कोड सैंपल Google API की क्लाइंट लाइब्रेरी का इस्तेमाल करके बैच अनुरोध करने का तरीका बताते हैं. लाइब्रेरी इंस्टॉल करने और उन्हें सेट अप करने के तरीके के बारे में ज़्यादा जानकारी के लिए, क्विकस्टार्ट गाइड देखें.

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