ติดตั้งใช้งานและจัดการคําขอด้วยบริการรวบรวมข้อมูล

หลังจากติดตั้งใช้งานบริการรวบรวมข้อมูลเรียบร้อยแล้ว คุณจะใช้ปลายทาง createJob และ getJob เพื่อโต้ตอบกับบริการได้ แผนภาพต่อไปนี้แสดงภาพสถาปัตยกรรมการติดตั้งใช้งานสำหรับปลายทางทั้ง 2 นี้

ภาพรวม Aggregation Service API
รูปที่ 1ภาพรวมของ Aggregation Service API

อ่านเพิ่มเติมเกี่ยวกับปลายทาง 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 สตริง นี่คือเส้นทางของที่เก็บข้อมูล สำหรับไฟล์เดียว คุณสามารถใช้เส้นทางได้ สำหรับไฟล์หลายไฟล์ คุณสามารถใช้คำนำหน้าในเส้นทางได้
ตัวอย่าง: โฟลเดอร์/ไฟล์จะรวบรวมรายงานทั้งหมดจากโฟลเดอร์/ไฟล์1.avro, โฟลเดอร์/ไฟล์/ไฟล์1.avro และโฟลเดอร์/ไฟล์1/test/ไฟล์2.avro
input_data_bucket_name สตริง นี่คือที่เก็บข้อมูลสําหรับข้อมูลอินพุตหรือรายงานที่รวบรวมได้ ซึ่งอยู่ในพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณา
output_data_blob_prefix สตริง นี่คือเส้นทางเอาต์พุตในที่เก็บข้อมูล รองรับไฟล์เอาต์พุตเดียว
output_data_bucket_name สตริง นี่คือที่เก็บข้อมูลที่จะส่ง output_data ไป ซึ่งอยู่ในพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณา
job_parameters พจนานุกรม ฟิลด์ที่ต้องกรอก ฟิลด์นี้มีฟิลด์ต่างๆ เช่น
  • output_domain_blob_prefix
  • output_domain_bucket_name
  • attribution_report_to
  • reporting_site
  • debug_privacy_epsilon
  • report_error_threshold_percentage
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 การรายงานหรือต้นทางการรายงานที่ได้รับรายงาน ระบบจะลงทะเบียนต้นทางของเว็บไซต์ในการเริ่มต้นใช้งานบริการรวมข้อมูล
job_parameters.reporting_site สตริง ใช้พร้อมกับ attribution_report_to ไม่ได้ นี่คือชื่อโฮสต์ของ URL การรายงานหรือต้นทางการรายงานที่ได้รับรายงาน ระบบจะลงทะเบียนต้นทางของเว็บไซต์ในการเริ่มต้นใช้งานบริการรวมข้อมูล หมายเหตุ: คุณอาจส่งรายงานหลายรายการที่มีต้นทางต่างกันภายในคำขอเดียวได้ โดยมีเงื่อนไขว่าต้นทางทั้งหมดเป็นของเว็บไซต์รายงานเดียวกันที่ระบุไว้ในพารามิเตอร์นี้
job_parameters.debug_privacy_epsilon จุดลอยตัว, Double ช่องที่ไม่บังคับ หากไม่ได้ส่งค่า ระบบจะใช้ค่าเริ่มต้นเป็น 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 บูลีน ช่องที่ไม่บังคับ เมื่อเรียกใช้การแก้ไขข้อบกพร่อง ระบบจะเพิ่มรายงานสรุปการแก้ไขข้อบกพร่องที่มีและไม่มีการเพิ่มสัญญาณรบกวน รวมถึงคำอธิบายประกอบ เพื่อระบุว่าคีย์ใดอยู่ในอินพุตโดเมนและ/หรือรายงาน นอกจากนี้ ระบบจะไม่บังคับใช้รายการที่ซ้ำกันในแต่ละกลุ่มด้วย โปรดทราบว่าการเรียกใช้การแก้ไขข้อบกพร่องจะพิจารณารายงานที่มีแฟล็ก "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 จุดลอยตัว, Double ช่องที่ไม่บังคับ หากไม่ได้ส่งค่า ระบบจะใช้ค่าเริ่มต้นเป็น 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")