이 페이지는 Cloud Translation API를 통해 번역되었습니다.

집계 가능한 보고서 수신 및 저장

광고 기술이 측정 API (Attribution Reporting API 또는 Private Aggregation API)를 트리거하면 암호화된 보고서가 Chrome 브라우저 / 클라이언트 측에서 광고 기술의 보고 출처가 포함된 .well-known URL인 광고 기술의 보고 엔드포인트로 전송됩니다. 보고 엔드포인트는 암호화된 보고서를 수집하기 위해 광고 기술에서 호스팅합니다.

다음은 API별 엔드포인트입니다.

Private Aggregation
- [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage 디버그
- 실시간 [reporting-origin]/.well-known/private-aggregation/report-shared-storage 또는 /.well-known/private-aggregation/report-protected-audience
기여도 보고
- [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution 디버그
- 라이브 [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

광고 기술은 POST 호출을 통해 JSON 형식의 보고서를 수신합니다. 광고 기술은 이러한 JSON 보고서를 수집한 후 집계 서비스에 사용되는 AVRO 형식으로 변환합니다. 변환된 AVRO 보고서는 나중에 일괄 처리하기 위해 광고 기술의 클라우드 저장소에 저장됩니다.

광고 기술이 일괄 처리 준비가 되면 광고 기술은 집계 서비스에서 집계 작업 요청을 트리거합니다. 이때 집계 서비스에서 광고 기술의 클라우드 스토리지에서 보고서를 가져옵니다. 집계 서비스는 광고 기술의 클라우드 스토리지에 호스팅되며 허용 목록에 추가된 이미지가 있어야 합니다.

접수된 신고는 다음과 유사합니다.

Private Aggregation API

  {
    "aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
    "aggregation_service_payloads": [ {
        "key_id": "1a2baa3f-5d48-46cf-91f0-772633c12640",
        "payload": "8Cjr1s3FVkCYkjzBvyzJn14yardVjd5N4vLCA69LQAPbIkJ0B58hAqUGBCNXpvTjW9ZpIoZbCSiUOsUDuoA/S+tqVolLMkame6sWC07cfUmZcVsbU+La3pzTMtCgdtNc8MIWgD3C63CMw7rWroRlechewVUajvAYVK/0HJq0YyGrTiFZZm36zi0jjyHLAXKV8p1Lvy1d0o/wnBxC5oVo5BV6LPkxqQEcoYS2GyixUuht6wD0RzuH+BxxuH6vY/ynp2xDrnwftjvqwDUAxUWLFTunthM6BXZVxlrvOBim1h2dvPqWSyKZ5gafo+MgW9EM4SraavNM3XzZSCjdtAfSMJMrynSu2j0opyAq+9e1jq1xeYN00yZrJ0Y/GTI45IGjgCnVmvmuoI9ucW2SnXP31CQBwHqk4gtUgMsYGFSUYfhtnAQ/8TSbaXyS2LX+cQW87LqkvIraWw6o37O24VFBreFoFFXpu3IUeCZfji+Sr4/ykfZuHeMzQbBavyNnHKzPZlbLSXMiucx4/vWzYyOzHeIlbtupXVvbi40V2PieDShaSbjI266kGgFkeCk6z51AaAGebDPtRT1lhBpcoQ6JdF0Yp5VWSnyFARKFtCZ1aEBrlUlrEHLUQY/pFtmDxJQiicRz1YPjR8jRr3C7hlRhWwov0dMocqnMz5209hHGVZWSsaGc9kWjtxREW2ULXfoIwOGbX+WZsyFW2RhXksQPJ5fhyNc4ROkAzUthLb68gC5e0yZHvmLIAU4hcWe0UanJv+jRljn8PAPaJHKFUxQNJyBA7mTbn5mkpycxGrX6T3ZYdPHqvckqt9llJZWjr8NneizzZFRuJk423BDs38fXkvcTAsAckd2Zu0u2KC45WR93sN2/CWrqB7/QU9BsgNdonl/ehAWhU1LbcRRvBTcR9+0wL7vRL7cv5LG3+gRYRKsWI6U2nDSWp0cNpo9+HU0JNiifa5X0cguihqU2bSk6ABozgRtCZ7m+7eqWXMLSzBdmc1CPUoQppo6Wmf6ujdNqI6v2S6pDH781lph8Z2v7ZpxGdhVVPEL51cVn"
    } ],
    "debug_key": "1234",
    "shared_info": "{\"api\":\"shared-storage\",\"report_id\":\"05e3b948-cb8d-4404-be29-bfeac7ad9710\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707784729\",\"version\":\"0.1\"}"
  }

Attribution Reporting API

  {
    "aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
    "aggregation_service_payloads": [ {
        "key_id": "2dee0f3f-2aee-4a4a-8238-9154ed3d6f72",
        "payload": "pHvTHhcxvNKaCmnLpvYQsXlJpiNRuFO5Zj1QqUlqgWPOfuoHLfiXiFjmpvY8a53/OYnS4bKwHwJReFcofldsu8E9BzTTJ3CEk+B7vbEjnDPaljhpIBMTuQXy3QHGK4slWR/yNZVm2uXRWR/DVVzXziBoTDjN7qaPstRoLKUUMdfY2u8oq4tnLY00Y+NDZttZ4wJvC7hPmvY3lqHjdl14JPD2ytZZ4NViYzno3WKdH/oZc0jhGK4zI38lAM0qpahF/B9yb4zOu7IRIjQpNx73P8naDyddxLldoVlW/qHpO04FguWymscvI/8i6NwUR6Kj8seRlWS0iIUhETt/ai3lilKUHUb+uz0YG2kxjoXq7Ldk+MP56nNl67ZRNi2YZ7bOGI/okYWoT/wt2uWPe/5xAEMmadxl0hQQrG7YXHRSD8rDnaVPXo+AKIxdg727yJeB1ZENZvovl/kIevdRAmdBe2h1U3J6Uz6psly/46fvjgkj5QD+kO2uaYirzvmwS19luJsN/Qvh/R3ZO4qlJIQI0nDJPWwUJ4ODpyVmj4a0xQp3t2ESEnf4EmY7+khn3xpF5+MwEWKES2ZeDf7SHalR99pvZA8G3Fr8M0PWFmT00cmKCBwpQgZyd3Eay70UlqdkbFEedxiCVWKNNOUz41m5KG/7K3aR+dYx57l57Wct4gOFQg3jiUEBJWrFIVCXf12BT5iz5rBQh1N1CUt2oCOhYL/sPuBl6OV5GWHSIj8FUdpoDolqKXWINXfE88MUijE2ghNRpJN25BXIErUQtO9wFQv7zotC6d2BIaF0x8AkKg/7yzBQRySX/FZP3H3lMkpOz9rQMV8DjZ2lz7nV4k6CFo8qhT6cpYJD7GpYl81xJbglNqcJt5Pe5YUHrdBMyAFsTh3yoJvYnhQib/0xVN/a93lbYccxsd0yi375n4Xz0i1HUoe2ps+WlU8XysAUA1agG936eshaY1anTtbJbrcoaH+BNSacKiq4saprgUGl4eDjaR/uBhvUnO52WkmAGon8De3EFMZ/kwpPBNSXi7/MIAMjotsSKBc19bfg"
    } ],
    "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://privacy-sandbox-demos-shop.dev\",\"report_id\":\"5b052748-f5fb-4f14-b291-de03484ed59e\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707786751\",\"source_registration_time\":\"0\",\"version\":\"0.1\"}",
    "source_debug_key": "123456789",
    "trigger_debug_key": "123456789"
  }

JSON을 AVRO 보고서로 변환

일괄 처리할 때는 집계 가능한 보고서가 AVRO 형식이어야 합니다. AVRO 보고서를 만들려면 보고서 AVRO 스키마 (AVSC)가 필요합니다.

집계 서비스 GitHub 저장소에서 샘플 JavaScript 코드를 확인할 수 있습니다.

다음은 집계 가능한 보고서의 AVRO 스키마입니다. 보고서의 다양한 필드는 payload, key_id, shared_info입니다.

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }

매개변수	유형	설명
`payload`	바이트	실시간 / 프로덕션 보고서의 경우 페이로드를 base64로 디코딩하고 `payload`에서 바이트 배열로 변환해야 합니다.
`debug_cleartext_payload`	바이트	디버그 보고서의 경우 페이로드를 base64로 디코딩하고 `debug_cleartext_payload`에서 바이트 배열로 변환해야 합니다.
`key_id`	문자열	보고서에 있는 key_id 문자열입니다. key_id는 이와 유사한 128비트 범용 고유 식별자입니다.
`shared_info`	문자열	보고서 shared_info 필드에서 발견된 변조되지 않은 문자열입니다.

다음은 보고서 JSON의 예입니다.

{ 
   "aggregation_coordinator_identifier": "aws-cloud",      
   "aggregation_service_payloads": [{ 
      "debug_cleartext_payload": "omRkYXhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWW1vcGVyYX", 
      "key_id": "3c6e2850-edf6-4886-eb70-eb3f2a7a7596",
      "payload": "oapYz92Mb1yam9YQ2AnK8dduTt2RwFUSApGcKqXnG1q+aGXfJ5DGpSxMj0NxdZgp7Cq" 
   }],
   "debug_key": "1234", 
   "shared_info":
"{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"b029b922-93e9-4d66-a8c6-8cdeec762aed\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1719251997\",\"version\":\"0.1\"}"
}

출력 도메인 AVRO

집계 서비스를 사용하여 요약 보고서를 생성하려면 광고 기술에 집계 가능한 보고서와 도메인 파일이 필요합니다. 집계 가능한 보고서는 보고 출처에서 수신되고 AVRO 형식으로 변환된 JSON 보고서입니다. 출력 도메인에는 집계 가능한 보고서에서 수집되고 요약 보고서에 작성되는 사전 선언된 키가 포함됩니다. 기여 분석 보고서의 키 및 비공개 집계의 키에 대해 자세히 알아보세요. 출력 도메인에는 필드 버킷이 포함되며 버킷 값은 버킷 키입니다.

도메인 파일도 다음 스키마를 사용하는 AVRO 형식이어야 합니다.

  {
    "type": "record",
    "name": "AggregationBucket",
    "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "A single bucket that appears in the aggregation service output. 128-bit integer encoded as a 16-byte big-endian bytestring."
      }
    ]
  }

버킷 키

버킷 키는 버킷 키의 16진수 바이트 문자열이어야 합니다. Decimal에서 키가 1369인 경우를 예로 들 수 있습니다. 16진수로 변환하면 559가 됩니다. 그런 다음 559를 출력 도메인 AVRO에 추가할 바이트 문자열로 변환해야 합니다.

일괄 보고서

개인 정보 보호 예산 및 일괄 처리에 대해 자세히 알아보려면 일괄 처리 전략 문서를 참고하세요. 또한 집계 가능한 보고서는 특정 기간 내에만 일괄 처리할 수 있습니다. 보고서는 scheduled_report_time와 일괄 실행 날짜 (현재 90일) 사이의 MAX_REPORT_AGE를 초과해서는 안 됩니다.

요약 보고서

일괄 처리 후 집계 서비스는 AVRO 형식의 요약 보고서를 만듭니다. 요약 보고서는 results.avsc 스키마를 사용합니다.

요약 보고서는 createJob 요청에 명시된 output_data_bucket_name 버킷의 output_data_blob_prefix에 있습니다.

debug_run이 사용 설정된 집계 서비스 배치의 경우 두 개의 보고서가 생성됩니다. 요약 보고서 및 디버그 요약 보고서 디버그 요약 보고서는 output_data_blob_prefix/debug 폴더에 있습니다.

생성된 디버그 보고서는 debug_results.avsc 스키마를 사용합니다.

요약 보고서와 디버그 보고서 모두 이름이 [output_data_blob_prefix]-1-of-1.avro로 지정됩니다. output_data_blob_prefix가 summary/summary.avro이면 보고서가 summary-1-of-1.avro라는 이름으로 요약 폴더에 저장됩니다.

results.avsc

{
  "type": "record",
  "name": "AggregatedFact",
  "fields": [
    {
      "name": "bucket",
      "type": "bytes",
      "doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
    },
    {
      "name": "metric",
      "type": "long",
      "doc": "Metric associated with the bucket"
    }
  ]
}

debug_results.avsc

  {
  "type": "record",
  "name": "DebugAggregatedFact",
  "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
      },
      {
        "name": "unnoised_metric",
        "type": "long",
        "doc": "Unnoised metric associated with the bucket."
      },
      {
        "name": "noise",
        "type": "long",
        "doc": "The noise applied to the metric in the regular result."
      }
      {
        "name":"annotations",
        "type": {
          "type": "array",
          "items": {
            "type":"enum",
            "name":"bucket_tags",
            "symbols":["in_domain","in_reports"]
          }
       }
    ]
  }

변환되면 요약 보고서가 results.json 예와 같이 표시됩니다. debug_run이 사용 설정된 경우 디버그 요약 보고서는 debug_results.json 예와 유사한 결과를 반환합니다.

results.json (예시)

집계 서비스에서 제공하는 AVRO 보고서는 버킷 키와 버킷 값의 노이즈가 추가된 요약 / 집계 값이 포함된 보고서와 유사해 보일 수 있습니다.

  {
    "bucket": "\u0005Y",
    "metric": 26308
  }

debug_results.json (예)

집계 서비스에서 전송되는 디버그 AVRO 보고서는 버킷 키, unnoised_metric (노이즈가 없는 버킷 키의 요약), unnoised_metric에 추가된 노이즈를 수신하는 다음과 유사해야 합니다.

  {
    "bucket": "\u0005Y",
    "unnoised_metric": 128,
    "noise": -17948,
    "annotations": [
      "in_reports",
      "in_domain"
    ]
  }

주석에는 다음을 의미하는 in_reports 또는 in_domain도 포함됩니다.

in_reports: 집계 가능한 보고서 내에서 버킷 키를 사용할 수 있습니다.
in_domain: 버킷 키는 output_domain AVRO 파일 내에서 사용할 수 있습니다.