เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API เข้าด้วยกันเพื่อลดจำนวนการเชื่อมต่อ HTTP ที่ไคลเอ็นต์ต้องสร้าง
เอกสารนี้เกี่ยวกับการสร้างคำขอแบบกลุ่มโดยการส่งคำขอ HTTP แต่หากคุณใช้ไลบรารีของไคลเอ็นต์ Google เพื่อส่งคำขอแบบกลุ่ม โปรดดูเอกสารประกอบของไลบรารีไคลเอ็นต์
ภาพรวม
การเชื่อมต่อ HTTP แต่ละครั้งที่ไคลเอ็นต์ทำให้เกิดโอเวอร์เฮดจำนวนหนึ่ง Display & Video 360 API รองรับการทำงานแบบกลุ่มเพื่อให้ไคลเอ็นต์รวมการเรียก API หลายรายการไว้ในคำขอ HTTP รายการเดียวได้
ตัวอย่างสถานการณ์ที่คุณอาจต้องใช้การทำงานแบบกลุ่มมีดังนี้
- การเรียกดูแหล่งข้อมูลจากผู้ลงโฆษณาหลายราย
- การสร้างหรืออัปเดตทรัพยากรหลายรายการพร้อมกัน
- การแก้ไขการกำหนดเป้าหมายในรายการโฆษณาหลายรายการ
ในแต่ละกรณี คุณสามารถจัดกลุ่มการโทรเข้าด้วยกันเป็นคำขอ HTTP รายการเดียว แทนการส่งแต่ละสายแยกกันได้ คำขอภายในทั้งหมดต้องไปยัง Google API เดียวกัน
คุณสามารถโทรได้ไม่เกิน 1,000 สายต่อคำขอเป็นกลุ่ม หากต้องการให้มีการเรียกมากกว่านั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ
หมายเหตุ: ระบบแบบกลุ่มสำหรับ API ของ Display & Video 360 จะใช้ไวยากรณ์เดียวกันกับระบบการประมวลผลแบบกลุ่มของข้อมูล OData แต่อรรถศาสตร์จะแตกต่างกันไป
รายละเอียดกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการรวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งสามารถส่งไปยัง batchPath
ที่ระบุไว้ในเอกสารการค้นพบ API ได้ เส้นทางเริ่มต้นคือ /batch/api_name/api_version
ส่วนนี้อธิบายไวยากรณ์แบบกลุ่มโดยละเอียด ต่อไปจะเป็นตัวอย่าง
หมายเหตุ: คำขอ n ชุดหนึ่งที่จัดกลุ่มเข้าด้วยกันจะนับรวมในขีดจำกัดการใช้งานของคุณเป็นคำขอ n ไม่ใช่คำขอเดียว ระบบจะแยกคำขอแบบกลุ่มเป็นชุดคำขอก่อนประมวลผล
รูปแบบคำขอแบบกลุ่ม
คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก API ของ Display & Video 360 หลายรายการโดยใช้ประเภทเนื้อหา multipart/mixed
แต่ละส่วนภายในคำขอ HTTP หลักนั้นจะมีคำขอ HTTP ที่ซ้อนกันอยู่
แต่ละส่วนจะเริ่มต้นด้วยส่วนหัว HTTP Content-Type: application/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
ตัวอย่าง
ตัวอย่างต่อไปนี้แสดงการใช้การจัดกลุ่มกับ API ของ Display & Video 360
ตัวอย่างคำขอแบบกลุ่ม
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 APIs ดูคู่มือเริ่มใช้งานฉบับย่อที่เกี่ยวข้องสำหรับข้อมูลเพิ่มเติม เกี่ยวกับวิธีติดตั้งและตั้งค่าไลบรารี
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);