집계 서비스를 배포한 후 createJob
및 getJob
엔드포인트를 사용하여 서비스와 상호작용할 수 있습니다. 다음 다이어그램은 이러한 두 엔드포인트의 배포 아키텍처를 시각적으로 보여줍니다.

createJob
및 getJob
엔드포인트에 대한 자세한 내용은 Aggregation Service API 문서를 참고하세요.
작업 만들기
작업을 만들려면 createJob
엔드포인트로 POST 요청을 전송합니다.
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>"
}
}
작업 생성에 성공하면 202 HTTP 상태 코드가 반환됩니다.
reporting_site
와 attribution_report_to
는 상호 배타적이며 둘 중 하나만 필요합니다.
job_parameters
에 debug_run
를 추가하여 디버그 작업을 요청할 수도 있습니다.
디버그 모드에 관한 자세한 내용은 집계 디버그 실행 문서를 참고하세요.
{
"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 |
문자열 |
광고 기술에서 생성한 고유 식별자로, 128자(영문 기준) 이하의 ASCII 문자여야 합니다. 이렇게 하면 일괄 작업 요청이 식별되고 광고 기술의 클라우드 스토리지에 호스팅된 `input_data_bucket_name` 에 지정된 입력 버킷에서 `input_data_blob_prefix` 에 지정된 집계 가능한 모든 AVRO 보고서가 가져옵니다.
문자: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
|
input_data_blob_prefix |
문자열 |
버킷 경로입니다. 단일 파일의 경우 경로를 사용할 수 있습니다. 여러 파일의 경우 경로에 접두사를 사용할 수 있습니다.
예: folder/file은 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 와 마찬가지로 출력 도메인 AVRO가 있는 output_domain_bucket_name 의 경로입니다. 여러 파일의 경우 경로에 접두사를 사용할 수 있습니다. 집계 서비스가 일괄 처리를 완료하면 요약 보고서가 생성되어 output_data_blob_prefix 이름으로 출력 버킷 output_data_bucket_name 에 배치됩니다.
|
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 |
문자열 |
선택 입력란입니다. 서명되지 않은 필터링 ID 목록으로 쉼표로 구분됩니다. 일치하는 필터링 ID를 제외한 모든 참여는 필터링됩니다. (예:"filtering_ids": "12345,34455,12" ). 기본값은 0입니다.
|
job_parameters.debug_run |
불리언 |
선택 입력란입니다. 디버그 실행을 실행하면 노이즈가 있는 디버그 요약 보고서와 노이즈가 없는 디버그 요약 보고서 및 주석이 추가되어 도메인 입력 또는 보고서에 있는 키를 나타냅니다. 또한 일괄 처리 내 중복도 적용되지 않습니다. 디버그 실행은 "debug_mode": "enabled" 플래그가 있는 보고서만 고려합니다. v2.10.0부터 디버그 실행은 개인 정보 보호 예산을 소비하지 않습니다.
|
작업 가져오기
광고 기술이 요청된 일괄 처리의 상태를 확인하려면 getJob
엔드포인트를 호출하면 됩니다. getJob
엔드포인트는 job_request_id
매개변수와 함께 HTTPS GET 요청을 사용하여 호출됩니다.
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 요청에 지정된 고유한 작업/일괄 처리 ID입니다.
|
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://1.exampleabc.com 등) 또는 완전히 다른 도메인 (https://3.examplexyz.com )의 보고서가 포함되어 있더라도 https://exampleabc.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 |
문자열 |
선택 입력란입니다. 서명되지 않은 필터링 ID 목록이며 쉼표로 구분됩니다. 일치하는 필터링 ID를 제외한 모든 참여는 필터링됩니다. 이는 createJob 요청에 지정됩니다.
(예: "filtering_ids":"12345,34455,12" . 기본값은 '0'입니다.)
|