Aggregation Service API 이해

배포 후 집계 서비스는 광고 기술 사용을 위한 두 개의 엔드포인트(createJob 및 getJob)를 노출합니다.

AgS 다이어그램

createJob 및 getJob 엔드포인트에 관한 자세한 내용은 Aggregation Service API 문서를 참고하세요.

createJob

createJob 엔드포인트는 HTTP POST 요청을 통해 호출되며 요청 본문이 필요합니다. createJob 요청이 완료되면 HTTP 202 성공 응답을 수신합니다.

  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>"
  }
}

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 딕셔너리 필수 입력란입니다. 여기에는 다음과 같은 다양한 필드가 포함됩니다.
  • 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 부동 소수점, 더블 선택적 필드입니다. 전달된 값이 없는 경우 기본값은 10입니다. 0~64의 값을 사용할 수 있습니다. 값은 다양할 수 있습니다.
job_parameters.report_error_threshold_percentage 더블 선택적 필드입니다. 작업이 실패하기 전에 실패할 수 있는 보고서 비율의 기준점입니다. 비워 두면 기본값은 10%입니다.
job_parameters.input_report_count long 값 선택 입력란입니다. 이 작업의 입력 데이터로 제공된 총 보고서 수입니다. 이 값은 report_error_threshold_percentage와 함께 사용하면 오류로 인해 보고서가 제외될 때 작업이 조기에 실패하도록 합니다.
job_parameters.filtering_ids 문자열 선택적 필드입니다. 쉼표로 구분된 서명되지 않은 필터링 ID 목록입니다. 일치하는 필터링 ID를 제외한 모든 참여는 필터링됩니다. 예: "filtering_ids": "12345,34455,12". 기본값은 '0'입니다.
job_parameters.debug_run 불리언 선택 입력란입니다. 디버그 실행을 실행할 때 노이즈가 포함되고 노이즈가 없는 디버그 요약 보고서와 주석이 추가되어 도메인 입력 및/또는 보고서에 어떤 키가 있는지 나타냅니다. 또한 배치 간에 중복이 적용되지 않습니다. 디버그 실행에서는 "debug_mode": "enabled" 플래그가 있는 보고서만 고려하며 디버그 실행 시 예산을 사용합니다.

getJob

광고 기술에서 요청된 일괄 처리의 상태를 확인하려면 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://2.exampleabc.com, https://3.examplexyz.com의 보고서를 추가하는 경우 작업에 등록된 보고 출처와 일치하는 버킷에 추가된 보고서만 집계됩니다(https://exampleabc.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 문자열 선택적 필드입니다. 서명되지 않은 필터링 ID 목록이며 쉼표로 구분됩니다. 일치하는 필터링 ID를 제외한 모든 참여는 필터링됩니다. 이는 createJob 요청에 지정됩니다. (예: "filtering_ids":"12345,34455,12". 기본값은 '0'입니다.)