집계 서비스로 요청 배포 및 관리

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

집계 서비스 API 개요
그림 1.Aggregation Service API 개요

createJobgetJob 엔드포인트에 대한 자세한 내용은 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_siteattribution_report_to상호 배타적이며 둘 중 하나만 필요합니다.

job_parametersdebug_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 딕셔너리 필수 입력란입니다. 이 필드에는 다음과 같은 다양한 필드가 포함됩니다.
  • 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와 마찬가지로 출력 도메인 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'입니다.)