คำขอแบบกลุ่ม

เอกสารนี้แสดงวิธีเรียก API แบบเป็นกลุ่มเพื่อลดจำนวนการเชื่อมต่อ HTTP ที่ไคลเอ็นต์ต้องสร้าง

เอกสารนี้เกี่ยวข้องกับการส่งคำขอแบบเป็นกลุ่มโดยการส่งคำขอ HTTP โดยเฉพาะ หากคุณใช้ไลบรารีของไคลเอ็นต์ Google เพื่อส่งคําขอแบบเป็นกลุ่มแทน โปรดดูเอกสารประกอบของไลบรารีของไคลเอ็นต์

ภาพรวม

การเชื่อมต่อ HTTP แต่ละรายการที่ไคลเอ็นต์สร้างขึ้นจะทำให้เกิดค่าใช้จ่ายเพิ่มเติมในจำนวนหนึ่ง Display & Video 360 API รองรับการรวมกลุ่มเพื่อให้ไคลเอ็นต์สามารถใส่การเรียก API หลายรายการไว้ในคําขอ HTTP รายการเดียว

ตัวอย่างสถานการณ์ที่คุณอาจต้องการใช้การแยกกลุ่มมีดังนี้

  • การดึงข้อมูลแหล่งข้อมูลจากผู้ลงโฆษณาหลายราย
  • การสร้างหรืออัปเดตทรัพยากรหลายรายการพร้อมกัน
  • การแก้ไขการกําหนดเป้าหมายในรายการโฆษณาหลายรายการ

ในแต่ละกรณี คุณสามารถจัดกลุ่มการเรียกแต่ละรายการไว้ในคําขอ HTTP รายการเดียวแทนการส่งการเรียกแต่ละรายการแยกกัน คำขอภายในทั้งหมดต้องส่งไปยัง Google API เดียวกัน

คุณโทรได้สูงสุด 1,000 ครั้งในคำขอแบบเป็นกลุ่มเดียว หากต้องโทรมากกว่านั้น ให้ใช้คำขอแบบเป็นกลุ่มหลายรายการ

หมายเหตุ: ระบบการประมวลผลเป็นกลุ่มสําหรับ Display & Video 360 API ใช้ไวยากรณ์เดียวกับระบบการประมวลผลเป็นกลุ่มของ OData แต่ความหมายจะแตกต่างกัน

รายละเอียดการประมวลผลเป็นกลุ่ม

คำขอกลุ่มประกอบด้วยการเรียก API หลายรายการที่รวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งสามารถส่งไปยัง batchPath ที่ระบุไว้ในเอกสารการค้นพบ API เส้นทางเริ่มต้นคือ /batch/api_name/api_version ส่วนนี้จะอธิบายไวยากรณ์ของกลุ่มอย่างละเอียด โดยจะมีตัวอย่างให้ดูในภายหลัง

หมายเหตุ: ชุดคําขอ n รายการที่ส่งเป็นกลุ่มจะนับรวมเป็นคําขอ n รายการ ไม่ใช่ 1 รายการตามขีดจํากัดการใช้งาน ระบบจะแยกคำขอเป็นชุดคำขอก่อนดำเนินการ

รูปแบบคำขอแบบเป็นกลุ่ม

คําขอกลุ่มคือคําขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก Display & Video 360 API หลายรายการ โดยใช้ประเภทเนื้อหา multipart/mixed ภายในคําขอ HTTP หลักนั้น แต่ละส่วนจะมีคําขอ HTTP ที่ฝังอยู่

แต่ละส่วนจะเริ่มต้นด้วยส่วนหัว Content-Type: application/http HTTP ของตัวเอง และอาจมีส่วนหัว Content-ID เสริมด้วย อย่างไรก็ตาม ส่วนหัวของส่วนมีไว้เพื่อระบุจุดเริ่มต้นของส่วนเท่านั้น โดยแยกจากคำขอที่ฝังอยู่ หลังจากเซิร์ฟเวอร์เปิดคำขอกลุ่มออกเป็นคำขอแยกต่างหาก ระบบจะไม่สนใจส่วนหัวของส่วน

เนื้อความของแต่ละส่วนคือคําขอ HTTP ที่สมบูรณ์ โดยมีกริยา, URL, ส่วนหัว และเนื้อหาของตัวเอง คำขอ HTTP ต้องมีเฉพาะส่วนของเส้นทางใน URL เท่านั้น ไม่อนุญาตให้ใช้ URL แบบเต็มในคำขอแบบเป็นกลุ่ม

ส่วนหัว HTTP สำหรับคำขอกลุ่มภายนอก ยกเว้นส่วนหัว Content- เช่น Content-Type จะมีผลกับคำขอทุกรายการในกลุ่ม หากคุณระบุส่วนหัว HTTP หนึ่งๆ ทั้งในคําขอภายนอกและการเรียกแต่ละรายการ ค่าของส่วนหัวการเรียกแต่ละรายการจะลบล้างค่าของส่วนหัวคําขอกลุ่มภายนอก ส่วนส่วนหัวของการโทรแต่ละครั้งจะมีผลกับการโทรครั้งนั้นเท่านั้น

เช่น หากคุณระบุส่วนหัวการให้สิทธิ์สําหรับการเรียกใช้ที่เฉพาะเจาะจง ส่วนหัวนั้นจะมีผลกับการเรียกใช้นั้นเท่านั้น หากคุณระบุส่วนหัวการให้สิทธิ์สําหรับคําขอภายนอก ส่วนหัวนั้นจะมีผลกับคําขอแต่ละรายการ เว้นแต่ว่าจะมีการลบล้างด้วยส่วนหัวการให้สิทธิ์ของตนเอง

เมื่อเซิร์ฟเวอร์ได้รับคําขอแบบเป็นกลุ่ม ก็จะใช้พารามิเตอร์การค้นหาและส่วนหัวของคําขอด้านนอก (ตามความเหมาะสม) กับแต่ละส่วน จากนั้นจะถือว่าแต่ละส่วนเป็นคําขอ HTTP แยกต่างหาก

การตอบสนองต่อคําขอแบบเป็นกลุ่ม

การตอบกลับของเซิร์ฟเวอร์คือการตอบกลับ HTTP มาตรฐานรายการเดียวที่มีประเภทเนื้อหา multipart/mixed แต่ละส่วนเป็นการตอบกลับคําขอรายการใดรายการหนึ่งในคําขอแบบเป็นกลุ่มตามลําดับเดียวกับคําขอ

แต่ละส่วนของคำตอบมีการตอบกลับ HTTP ที่สมบูรณ์ รวมถึงรหัสสถานะ ส่วนหัว และเนื้อหา เช่นเดียวกับส่วนต่างๆ ในคำขอ และเช่นเดียวกับส่วนต่างๆ ในคำขอ แต่ละส่วนของคำตอบจะมีส่วนหัว Content-Type อยู่ก่อนเพื่อระบุจุดเริ่มต้นของส่วนนั้น

หากส่วนใดส่วนหนึ่งของคําขอมีส่วนหัว Content-ID ส่วนที่เกี่ยวข้องของการตอบกลับก็จะมีส่วนหัว Content-ID ที่ตรงกัน โดยมีสตริง response- นำหน้าค่าเดิม ดังที่แสดงในตัวอย่างต่อไปนี้

หมายเหตุ: เซิร์ฟเวอร์อาจเรียกใช้การเรียกของคุณในลำดับใดก็ได้ โปรดทราบว่าระบบอาจไม่เรียกใช้คำสั่งตามลำดับที่คุณระบุ หากต้องการให้การเรียก 2 ครั้งเกิดขึ้นตามลําดับที่กําหนด คุณจะส่งการเรียกในคําขอเดียวไม่ได้ ให้ส่งการเรียกแรกแยกต่างหาก แล้วรอการตอบกลับการเรียกแรกก่อนส่งการเรียกที่ 2

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้การจํานวนมากกับ 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);