หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

**รูปที่ 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`	สตริง	นี่คือเส้นทางของที่เก็บข้อมูล สำหรับไฟล์เดี่ยว คุณจะใช้เส้นทางได้ สำหรับไฟล์หลายไฟล์ คุณสามารถใช้คำนำหน้าในเส้นทางได้ ตัวอย่าง: โฟลเดอร์/ไฟล์จะรวบรวมรายงานทั้งหมดจาก 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`	พจนานุกรม	ฟิลด์ที่ต้องกรอก ช่องนี้มีช่องต่างๆ เช่น `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 การรายงานหรือต้นทางการรายงานนี้จะเป็น 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")