หลังจากทำให้บริการรวบรวมข้อมูลใช้งานได้สําเร็จแล้ว คุณจะใช้ปลายทาง createJob และ getJob เพื่อโต้ตอบกับบริการได้ แผนภาพต่อไปนี้แสดงภาพสถาปัตยกรรมการติดตั้งใช้งานสําหรับปลายทางทั้ง 2 รายการนี้
อ่านข้อมูลเพิ่มเติมเกี่ยวกับปลายทาง createJob และ getJob ได้ในเอกสารประกอบของ Aggregation Service API
สร้างงาน
หากต้องการสร้างงาน ให้ส่งคำขอ POST ไปยังปลายทาง createJob
bash
POST https://<api-gateway>/stage/v1alpha/createJob
-+
ตัวอย่างเนื้อหาของคำขอสำหรับ createJob
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"reporting_site": "<host name of reporting origin>"
}
}
การสร้างงานที่สําเร็จจะแสดงรหัสสถานะ HTTP 202
โปรดทราบว่า reporting_site และ attribution_report_to ใช้ร่วมกันไม่ได้และต้องใช้เพียงรายการเดียว
นอกจากนี้ คุณยังส่งคำของานแก้ไขข้อบกพร่องได้โดยเพิ่ม debug_run ลงใน job_parameters
ดูข้อมูลเพิ่มเติมเกี่ยวกับโหมดแก้ไขข้อบกพร่องได้ที่เอกสารประกอบเกี่ยวกับการเรียกใช้การแก้ไขข้อบกพร่องการรวม
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"attribution_report_to": "<reporting origin of report>"
"debug_run": "true"
}
}
ฟิลด์คำขอ
| พารามิเตอร์ | ประเภท | คำอธิบาย |
|---|---|---|
job_request_id |
สตริง |
นี่เป็นตัวระบุที่ไม่ซ้ำซึ่งเทคโนโลยีโฆษณาสร้างขึ้น ซึ่งควรเป็นตัวอักษร ASCII ที่มีความยาวไม่เกิน 128 อักขระ ซึ่งจะระบุคําของานแบบเป็นกลุ่มและนํารายงาน AVRO ที่รวบรวมข้อมูลได้ทั้งหมดที่ระบุไว้ใน `input_data_blob_prefix` จากที่เก็บข้อมูลอินพุตที่ระบุไว้ใน `input_data_bucket_name` ซึ่งโฮสต์อยู่ในระบบพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณา
อักขระ: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
|
input_data_blob_prefix |
สตริง |
นี่คือเส้นทางของที่เก็บข้อมูล สำหรับไฟล์เดี่ยว คุณจะใช้เส้นทางได้ สำหรับไฟล์หลายไฟล์ คุณสามารถใช้คำนำหน้าในเส้นทางได้
ตัวอย่าง: โฟลเดอร์/ไฟล์จะรวบรวมรายงานทั้งหมดจาก folder/file1.avro, folder/file/file1.avro และ folder/file1/test/file2.avro |
input_data_bucket_name |
สตริง | นี่คือที่เก็บข้อมูลสําหรับข้อมูลอินพุตหรือรายงานที่รวบรวมได้ ซึ่งอยู่ในพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณา |
output_data_blob_prefix |
สตริง | นี่คือเส้นทางเอาต์พุตในที่เก็บข้อมูล ระบบรองรับไฟล์เอาต์พุตไฟล์เดียว |
output_data_bucket_name |
สตริง |
นี่คือที่เก็บข้อมูลที่จะส่ง output_data ข้อมูลนี้อยู่ในพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณา
|
job_parameters |
พจนานุกรม |
ฟิลด์ที่ต้องกรอก ช่องนี้มีช่องต่างๆ เช่น
|
job_parameters.output_domain_blob_prefix |
สตริง |
คล้ายกับ input_data_blob_prefix นี่เป็นเส้นทางใน output_domain_bucket_name ที่มีโดเมนเอาต์พุต AVRO อยู่ สำหรับไฟล์หลายไฟล์ คุณสามารถใช้คำนำหน้าในเส้นทางได้ เมื่อบริการรวบรวมข้อมูลประมวลผลกลุ่มเสร็จแล้ว ระบบจะสร้างรายงานสรุปและวางไว้ในที่เก็บข้อมูลเอาต์พุต output_data_bucket_name ที่มีชื่อ output_data_blob_prefix
|
job_parameters.output_domain_bucket_name |
สตริง | นี่คือที่เก็บข้อมูลสำหรับไฟล์ AVRO ของโดเมนเอาต์พุต ซึ่งอยู่ในพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณา |
job_parameters.attribution_report_to |
สตริง | ค่านี้ใช้แทนกันได้กับ "reporting_site" โดย URL การรายงานหรือต้นทางการรายงานนี้จะเป็น URL ที่ได้รับรายงาน แหล่งที่มาของเว็บไซต์จะได้รับการลงทะเบียนในการเริ่มต้นใช้งานบริการรวบรวมข้อมูล |
job_parameters.reporting_site |
สตริง |
ใช้ร่วมกับ attribution_report_to ไม่ได้ นี่คือชื่อโฮสต์ของ URL การรายงานหรือต้นทางการรายงานที่ได้รับรายงาน แหล่งที่มาของเว็บไซต์จะได้รับการลงทะเบียนในการเริ่มต้นใช้งานบริการรวบรวมข้อมูล
หมายเหตุ: คุณส่งรายงานหลายฉบับที่มีต้นทางต่างกันภายในคําขอเดียวได้ ตราบใดที่ต้นทางทั้งหมดเป็นของเว็บไซต์การรายงานเดียวกันที่ระบุไว้ในพารามิเตอร์นี้
|
job_parameters.debug_privacy_epsilon |
จุดลอยตัว, เลขทศนิยม | ช่องที่ไม่บังคับ หากไม่ได้ส่งค่าใดๆ ค่าเริ่มต้นจะเป็น 10 ใช้ค่าได้ตั้งแต่ 0 ถึง 64 |
job_parameters.report_error_threshold_percentage |
ดับเบิล | ช่องที่ไม่บังคับ นี่คือเปอร์เซ็นต์สูงสุดของรายงานที่ดำเนินการไม่สำเร็จซึ่งอนุญาตได้ก่อนที่งานจะดำเนินการไม่สำเร็จ หากปล่อยว่างไว้ ค่าเริ่มต้นจะเป็น 10% |
job_parameters.input_report_count |
ค่าแบบยาว |
ช่องที่ไม่บังคับ จํานวนรายงานทั้งหมดที่ระบุเป็นข้อมูลอินพุตสําหรับงาน ค่านี้ร่วมกับ report_error_threshold_percentage จะทําให้งานล้มเหลวตั้งแต่เนิ่นๆ เมื่อมีการยกเว้นรายงานเนื่องจากข้อผิดพลาด
|
job_parameters.filtering_ids |
สตริง |
ช่องที่ไม่บังคับ รายการรหัสการกรองที่ไม่ได้ลงนามที่คั่นด้วยคอมมา ระบบจะกรองข้อมูลทั้งหมดที่ไม่ใช่รหัสการกรองที่ตรงกันออก (เช่น"filtering_ids": "12345,34455,12") ค่าเริ่มต้นคือ 0
|
job_parameters.debug_run |
บูลีน |
ช่องที่ไม่บังคับ เมื่อเรียกใช้การแก้ไขข้อบกพร่อง ระบบจะเพิ่มรายงานสรุปการแก้ไขข้อบกพร่องที่มีและไม่มีสัญญาณรบกวน รวมถึงคำอธิบายประกอบเพื่อระบุคีย์ที่มีอยู่ในอินพุตโดเมนและ/หรือรายงาน นอกจากนี้ ระบบจะไม่บังคับใช้รายการที่ซ้ำกันในกลุ่มต่างๆ ด้วย โปรดทราบว่าการเรียกใช้การแก้ไขข้อบกพร่องจะพิจารณาเฉพาะรายงานที่มี Flag "debug_mode": "enabled" เท่านั้น ตั้งแต่ v2.10.0 การเรียกใช้การแก้ไขข้อบกพร่องจะไม่ใช้งบประมาณความเป็นส่วนตัว
|
รับงาน
เมื่อเทคโนโลยีโฆษณาต้องการทราบสถานะของกลุ่มที่ขอ ก็สามารถเรียกใช้ปลายทาง getJob ระบบจะเรียกใช้ปลายทาง getJob โดยใช้คําขอ HTTPS GET พร้อมกับพารามิเตอร์ job_request_id
GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>
คุณควรได้รับการตอบกลับที่แสดงสถานะงานพร้อมข้อความแสดงข้อผิดพลาด
{
"job_status": "FINISHED",
"request_received_at": "2023-07-17T19:15:13.926530Z",
"request_updated_at": "2023-07-17T19:15:28.614942839Z",
"job_request_id": "PSD_0003",
"input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
"input_data_bucket_name": "ags-report-bucket",
"output_data_blob_prefix": "summary/summary.avro",
"output_data_bucket_name": "ags-report-bucket",
"postback_URL": "",
"result_info": {
"return_code": "SUCCESS",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-07-17T19:15:28.607802354Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "ags-report-bucket",
"output_domain_blob_prefix": "output_domain/output_domain.avro",
"attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
},
"request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}
ช่องคำตอบ
| พารามิเตอร์ | ประเภท | คำอธิบาย |
|---|---|---|
job_request_id |
สตริง |
รหัสนี้เป็นรหัสงาน/กลุ่มที่ไม่ซ้ำกันซึ่งระบุไว้ในคำขอ createJob
|
job_status |
สตริง | สถานะคำของาน |
request_received_at |
สตริง | เวลาที่ได้รับคำขอ |
request_updated_at |
สตริง | เวลาที่อัปเดตงานครั้งล่าสุด |
input_data_blob_prefix |
สตริง |
นี่คือคำนำหน้าข้อมูลอินพุตที่ตั้งค่าไว้ที่ createJob
|
input_data_bucket_name |
สตริง |
นี่คือที่เก็บข้อมูลอินพุตของเทคโนโลยีโฆษณาที่เก็บรายงานที่รวบรวมได้ ช่องนี้ตั้งค่าไว้ที่ createJob
|
output_data_blob_prefix |
สตริง |
นี่คือคำนำหน้าข้อมูลเอาต์พุตที่ตั้งค่าไว้ที่ createJob
|
output_data_bucket_name |
สตริง |
นี่คือที่เก็บข้อมูลเอาต์พุตของเทคโนโลยีโฆษณาที่เก็บรายงานสรุปที่สร้างขึ้น ช่องนี้ตั้งค่าไว้ที่ createJob
|
request_processing_started_at |
สตริง |
เวลาที่เริ่มการประมวลผลครั้งล่าสุด ซึ่งไม่รวมเวลาที่รอในคิวงาน
(เวลาประมวลผลทั้งหมด = request_updated_at - request_processing_started_at)
|
result_info |
พจนานุกรม |
ข้อมูลนี้เป็นผลการค้นหาของคำขอ createJob และประกอบด้วยข้อมูลทั้งหมดที่มี
ซึ่งแสดงค่า return_code, return_message, finished_at และ error_summary
|
result_info.return_code |
สตริง | รหัสผลลัพธ์ของงาน ข้อมูลนี้จําเป็นสําหรับการแก้ปัญหาหากเกิดปัญหาในบริการรวบรวมข้อมูล |
result_info.return_message |
สตริง | ข้อความแสดงความสำเร็จหรือความล้มเหลวที่แสดงผลจากงาน ข้อมูลนี้ยังจําเป็นสําหรับการแก้ปัญหาบริการรวบรวมข้อมูลด้วย |
result_info.error_summary |
พจนานุกรม | ข้อผิดพลาดที่แสดงผลจากงาน ข้อมูลนี้ประกอบด้วยจํานวนรายงานและประเภทข้อผิดพลาดที่พบ |
result_info.finished_at |
การประทับเวลา | การประทับเวลาที่บ่งบอกการเสร็จสิ้นของงาน |
result_info.error_summary.error_counts |
รายการ |
ซึ่งจะแสดงรายการข้อความแสดงข้อผิดพลาดพร้อมกับจํานวนรายงานที่ดำเนินการไม่สำเร็จพร้อมข้อความแสดงข้อผิดพลาดเดียวกัน จำนวนข้อผิดพลาดแต่ละรายการจะมีหมวดหมู่ error_count และ description
|
result_info.error_summary.error_messages |
รายการ | ซึ่งจะแสดงรายการข้อความแสดงข้อผิดพลาดจากรายงานที่ประมวลผลไม่สำเร็จ |
job_parameters |
พจนานุกรม |
ซึ่งประกอบด้วยพารามิเตอร์งานที่ให้ไว้ในคําขอ createJob พร็อพเพอร์ตี้ที่เกี่ยวข้อง เช่น `output_domain_blob_prefix` และ `output_domain_bucket_name`
|
job_parameters.attribution_report_to |
สตริง |
ใช้ร่วมกับ reporting_site ไม่ได้ นี่คือ URL การรายงานหรือต้นทางของรายงานที่ได้รับ ต้นทางเป็นส่วนหนึ่งของเว็บไซต์ที่ลงทะเบียนในการเริ่มต้นใช้งานบริการรวบรวมข้อมูล ข้อมูลนี้ระบุอยู่ในคำขอ createJob
|
job_parameters.reporting_site |
สตริง |
ใช้ร่วมกับ attribution_report_to ไม่ได้ นี่คือชื่อโฮสต์ของ URL การรายงานหรือต้นทางที่ได้รับรายงาน ต้นทางเป็นส่วนหนึ่งของเว็บไซต์ที่ลงทะเบียนในการเริ่มต้นใช้งานบริการรวบรวมข้อมูล โปรดทราบว่าคุณสามารถส่งรายงานที่มีแหล่งที่มาของการรายงานหลายรายการในคําขอเดียวกัน ตราบใดที่แหล่งที่มาของการรายงานทั้งหมดเป็นของเว็บไซต์เดียวกันที่ระบุไว้ในพารามิเตอร์นี้ ข้อมูลนี้ระบุอยู่ในคำขอ createJob นอกจากนี้ โปรดตรวจสอบว่าที่เก็บข้อมูลมีเฉพาะรายงานที่คุณต้องการรวบรวม ณ เวลาที่สร้างงาน ระบบจะประมวลผลรายงานที่เพิ่มลงในที่เก็บข้อมูลอินพุตซึ่งมีต้นทางการรายงานตรงกับเว็บไซต์การรายงานที่ระบุไว้ในพารามิเตอร์งาน
บริการรวบรวมข้อมูลจะพิจารณาเฉพาะรายงานภายในที่เก็บข้อมูลซึ่งตรงกับแหล่งที่มาของการรายงานที่ลงทะเบียนของงาน เช่น หากต้นทางที่ลงทะเบียนคือ https://exampleabc.com ระบบจะรวมเฉพาะรายงานจาก https://exampleabc.com แม้ว่าที่เก็บข้อมูลจะมีรายงานจากโดเมนย่อย (https://1.exampleabc.com ฯลฯ) หรือโดเมนอื่นโดยสิ้นเชิง (https://3.examplexyz.com) ก็ตาม
|
job_parameters.debug_privacy_epsilon |
จุดลอยตัว, เลขทศนิยม |
ช่องที่ไม่บังคับ หากไม่ได้ส่งค่าใดๆ ระบบจะใช้ค่าเริ่มต้น 10 ค่าที่ใช้ได้อยู่ในช่วง 0 ถึง 64 ค่านี้ระบุไว้ในคําขอ createJob
|
job_parameters.report_error_threshold_percentage |
ดับเบิล |
ช่องที่ไม่บังคับ นี่คือเปอร์เซ็นต์เกณฑ์ของรายงานที่อาจไม่ผ่านการตรวจสอบก่อนที่จะทําให้งานล้มเหลว หากไม่ได้กําหนดค่าไว้ ระบบจะใช้ค่าเริ่มต้น 10% ข้อมูลนี้ระบุอยู่ในคำขอ createJob
|
job_parameters.input_report_count |
ค่าขนาดยาว | ช่องที่ไม่บังคับ จํานวนรายงานทั้งหมดที่ระบุเป็นข้อมูลอินพุตสําหรับงานนี้ ค่า `report_error_threshold_percentage` ร่วมกับค่านี้จะทริกเกอร์ให้งานล้มเหลวก่อนเวลาอันควรหากมีการยกเว้นรายงานจํานวนมากเนื่องจากข้อผิดพลาด การตั้งค่านี้ระบุไว้ในคําขอ `createJob` |
job_parameters.filtering_ids |
สตริง |
ช่องที่ไม่บังคับ รายการรหัสการกรองที่ไม่ได้ลงนามที่คั่นด้วยคอมมา ระบบจะกรองข้อมูลทั้งหมดที่ไม่ใช่รหัสการกรองที่ตรงกันออก ข้อมูลนี้ระบุอยู่ในคำขอ createJob
(เช่น "filtering_ids":"12345,34455,12" ค่าเริ่มต้นคือ "0")
|