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

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

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

खास जानकारी

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

उन स्थितियों के उदाहरण, जब आपको एक साथ कई बैच बनाने की सुविधा इस्तेमाल करनी चाहिए:

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

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

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

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

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

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

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

बैच रिक्वेस्ट का फ़ॉर्मैट

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

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

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

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

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

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

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

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

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

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

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

उदाहरण

नीचे दिए गए उदाहरण में दिखाया गया है कि 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: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);