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

Private Aggregation API 기본사항

Private Aggregation API의 주요 개념

이 문서의 대상은 누구인가요?

Private Aggregation API 크로스 사이트 데이터에 액세스할 수 있는 워크렛에서 합산 데이터 수집을 지원합니다. 여기에 설명된 개념은 보고를 구축하는 개발자에게 중요합니다. Google Cloud Storage 및 Protected Audience API 내에서 작동합니다.

교차 사이트 보고 시스템을 구축하는 개발자인 경우 있습니다.
마케터, 데이터 과학자 또는 기타 요약 보고서인 경우 설계할 수 있도록 이러한 메커니즘을 이해하면 최적화된 요약 보고서를 검색할 수 있습니다.

핵심 용어

이 문서를 읽기 전에 다음 사항을 숙지하는 것이 좋습니다. 주요 용어와 개념에 대해 알아보겠습니다. 각 용어는 여기에서 자세히 설명합니다.

집계 키 (버킷이라고도 함)는 미리 정해진 데이터 포인트 모음입니다. 예를 들어 브라우저가 국가를 보고하는 위치 데이터 버킷을 수집합니다. 있습니다. 집계 키에는 2개 이상의 측정기준 (예: 국가 및 콘텐츠 위젯의 ID)입니다.
집계 가능한 값은 개별 데이터 포인트입니다. 집계 키로 수집됩니다. 얼마나 많은 사용자가 내 페이지처럼 사용자의 콘텐츠를 본 경우 France는 다음 기준의 측정기준입니다. 집계 키이고 1의 viewCount는 집계 가능한 값입니다.
집계 가능한 보고서는 브라우저 내에서 생성되고 암호화됩니다. 대상 Private Aggregation API: 단일 이벤트에 대한 데이터가 포함됩니다.
집계 서비스 집계 가능한 보고서의 데이터를 처리하여 요약 보고서를 만듭니다.
요약 보고서는 집계 서비스의 최종 출력입니다. 노이즈가 많은 집계된 사용자 데이터와 자세한 전환 데이터가 포함되어 있습니다.
Worklet은 하나의 특정 JavaScript 함수를 실행할 수 있게 해 주는 인프라의 요청자에게 정보를 반환합니다 워크렛 내에서 다음을 실행할 수 있습니다. JavaScript에 액세스할 수 있지만 외부 페이지와 상호작용하거나 커뮤니케이션할 수 없습니다.

비공개 집계 워크플로

집계 키와 브라우저에서 집계 가능한 보고서를 생성합니다. 보고서 보고서를 일괄 처리하는 서버로 전송됩니다. 일괄 보고서는 나중에 집계 서비스에서 처리되고 요약 보고서가 생성됩니다.

데이터는 클라이언트에서 수집기, 그리고 집계로 흐릅니다.
요약 보고서를 생성하는 서비스입니다.

Private Aggregation API를 호출하면 클라이언트 (브라우저)는 집계 가능한 보고서를 서버에 전송하여 수집하도록 합니다.
서버가 클라이언트에서 보고서를 수집하여 일괄 처리 집계 서비스로 전송됩니다.
충분한 보고서가 수집되면 이를 일괄 처리하여 집계 서비스는 신뢰할 수 있는 실행 환경에서 실행되어 요약 보고서입니다.

를 통해 개인정보처리방침을 정의할 수 있습니다.

이 섹션에 설명된 워크플로는 기여도 보고와 유사합니다. API를 참고하세요. 그러나 기여 분석은 보고는 노출 이벤트와 전환에서 수집된 데이터를 연결함 각기 다른 시간에 발생하는 이벤트입니다. 비공개 집계는 단일, 크로스 사이트 이벤트를 지원합니다.

집계 키

집계 키(줄여서 '키')는 집계 가능한 값이 누적됩니다. 하나 이상의 측정기준을 인코딩할 수 있습니다. 을 입력합니다. 측정기준은 더 많이 얻고자 하는 측면을 나타냅니다. 사용자의 연령대나 광고 노출수와 같은 확인할 수 있습니다.

예를 들어 여러 사이트에 삽입한 위젯이 있을 수 있고 위젯을 본 사용자의 국가를 분석하려는 경우 찾고 있습니다. '내 위젯을 본 사용자 중 몇 명이 어떻게 해야 할까요?" 이 질문에 대해 보고하려면 집계 키를 설정하면 됩니다. 이라는 두 가지 측정기준, 즉 위젯 ID와 국가 ID를 인코딩합니다.

Private Aggregation API에 제공된 키는 BigInt 여러 개의 측정기준으로 구성됩니다. 이 예에서 측정기준은 국가 ID, 위젯 ID, 국가 ID가 있습니다. 위젯 ID가 최대 4자리 숫자여야 한다고 가정해 보겠습니다. 1234와 같이 입력할 수 있고, 각 국가는 알파벳순으로 된 숫자로 아프가니스탄은 1, 프랑스는 61, 짐바브웨는 '195'입니다. 따라서 집계 가능한 키의 길이는 7자리이며 처음 4자리는 문자는 WidgetID 전용으로 예약되어 있으며 마지막 3자리는 CountryID용으로 예약되어 있습니다.

키가 프랑스 (국가 ID 061)의 사용자 수를 나타낸다고 가정해 보겠습니다. 위젯 ID 3276을(를) 본 사용자의 경우 집계 키는 3276061입니다.

집계 키
위젯 ID	국가 ID
3276	061

예: 측정기준에 사용 가능한 키 공간이 있는 경우 값이 더 적으면 앞에 0을 추가합니다. 예를 들어 국가 ID가 3자리를 허용하는 경우 알제리의 국가 ID는 003

집계 키는 다음과 같은 해싱 메커니즘으로도 생성할 수 있습니다. SHA-256 예를 들어 {"WidgetId":3276,"CountryID":67}는 해싱된 후 BigInt 값 42943797454801331377966796057547478208888578253058197330928948081739249096287n입니다. 해시 값이 128비트를 넘는 경우, 값을 자를 수 있습니다. 허용되는 최대 버킷 값(2^128−1)을 초과합니다.

공유 저장소 워크렛 내에서 crypto 및 모듈 TextEncoder개 해시를 생성하는 데 도움이 됩니다. 해시 생성에 대해 자세히 알아보려면 다음을 확인하세요. SubtleCrypto.digest() 켜짐 MDN

다음 예에서는 해싱된 키에서 버킷 키를 생성하는 방법을 설명합니다. 값:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

집계 가능한 값

집계 가능한 값은 여러 사용자의 키별로 합산되어 집계된 값이 생성됩니다. 요약 보고서에서 요약 값 형식으로 통계를 도출합니다

이제 앞서 제시한 질문 예시로 돌아가 보겠습니다. "사용자 수 내 위젯을 본 사람이 프랑스 출신인가요?" 이 질문에 대한 답변은 "제 위젯 ID 3276을 본 사용자 약 4,881명이 프랑스에서 온 해방입니다." 집계 가능한 값은 사용자당 1이며 '사용자 4881명' 은 해당 항목에 대해 집계 가능한 모든 값의 합계인 집계 값 집계 키.

집계 키		집계 가능한 값
위젯 ID	국가 ID	조회수
3276	061	1

이 예에서는 위젯을 보는 각 사용자에 대해 값을 1씩 증분합니다. 실제로는 집계 가능한 값을 확장하여 신호 대 노이즈를 개선할 수 있습니다. 비율을 사용합니다.

후원 예산

Private Aggregation API에 대한 각 호출을 contribution이라고 합니다. 보호 사용자 개인 정보 보호, 즉 개인 정보 보호 영역에서 수집할 수 있는 기여의 수를 제한이 있습니다

모든 집계 키에서 집계 가능한 모든 값을 합산할 때는 합계가 후원 예산보다 적어야 합니다. 예산 범위는 Worklet별로 지정됩니다. origin, 일일 및 Protected Audience API 및 공유 저장소 워크렛의 경우 별도의 역할을 합니다. 롤링 기간이 지난 24시간 정도가 하루 동안 사용됩니다. 새 집계 가능한 보고서를 사용하면 예산을 초과하게 되지만, 보고서는 생성됨.

참여 예산은 매개변수 L₁로 표시되며 하루 10분당 2¹⁶(65,536)으로 설정(백스톱 2²⁰)

(1,048,576) 자세한 내용은 설명 참조하세요.

참여 예산의 값은 임의적이지만 노이즈가 해당 값으로 조정됩니다. 이 예산을 사용하여 요약 값에서 신호 대 잡음비를 극대화할 수 있습니다. (노이즈 및 확장 섹션에서 더 자세히 설명함).

후원 예산에 대한 자세한 내용은 다음을 참조하세요. 설명을 참조하세요. 자세한 내용은 기여 예산 를 참조하세요.

집계 가능한 보고서

사용자가 Private Aggregation API를 호출하면 브라우저는 나중에 집계 서비스에서 처리할 수 있는 집계 가능한 보고서 시간을 내어 요약을 생성해 보고서를 참조하세요. 집계 가능한 보고서는 JSON 형식이며 암호화된 각각 {aggregation key, aggregatable value} 쌍입니다. 집계 가능한 보고서는 최대 1시간까지 무작위 지연으로 전송됩니다.

참여는 암호화되며 집계 서비스 외부에서 읽을 수 없습니다. 집계 서비스는 보고서를 복호화하고 요약 보고서를 생성합니다. 이 브라우저용 암호화 키 및 집계용 복호화 키 서비스는 키 관리 서비스 역할을 하는 조정자에 의해 제공됩니다. 조정자는 검증을 위해 서비스 이미지의 바이너리 해시 목록을 유지함 호출자가 복호화 키를 수신하도록 허용된 것입니다.

debug가 있는 집계 가능한 보고서의 예 모드가 사용 설정된 경우 다음을 실행합니다.

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

집계 가능한 보고서는 Ad Exchange 계정에서 chrome://private-aggregation-internals 페이지:

테스트를 위해 '선택한 보고서 보내기' 버튼을 사용하여 서버에 즉시 보고합니다.

집계 가능한 보고서 수집 및 일괄 처리

브라우저는 집계 가능한 보고서를 Worklet의 출처로 전송합니다. 비공개 집계 API 호출을 포함하며, 잘 알려진 경로:

공유 저장공간의 경우: /.well-known/private-aggregation/report-shared-storage
Protected Audience의 경우: /.well-known/private-aggregation/report-protected-audience

이러한 엔드포인트에서는 수집기 역할을 하는 서버를 운영해야 합니다. 클라이언트로부터 전송된 집계 가능한 보고서를 수신하는 데 사용됩니다.

그런 다음 서버에서 보고서를 일괄 처리하고 일괄 데이터를 집계에 전송합니다. 서비스. 암호화되지 않은 저장소에서 사용할 수 있는 정보를 기반으로 배치를 만듭니다. shared_info 필드와 같이 집계 가능한 보고서의 페이로드 이상적으로는 배치당 100개 이상의 보고서가 포함되어야 합니다.

매일 또는 매주 일괄 처리할 수 있습니다. 이 전략은 유연하며 또한 일괄 처리 전략을 변경하여 더 많은 볼륨(예: 더 많은 노출이 예상되는 날) 배치에는 동일한 API 버전, 보고 출처, 보고서 시간을 예약합니다.

Aggregation Service

서비스는 TEE에서 실행되고 집계 가능한 보고서를 복호화하고
최종 요약 보고서를 생성합니다.

집계 서비스 수집기에서 암호화된 집계 가능한 보고서를 수신하고 요약 생성 있습니다.

보고서 페이로드를 복호화하기 위해 집계 서비스는 복호화 키를 가져옵니다. 면담을 준비했습니다. 서비스가 TEE (신뢰할 수 있는 실행 환경)에서 실행되며, 이는 데이터 무결성, 데이터 기밀성, 코드 무결성도 포함됩니다 귀하가 서비스를 소유하고 운영하더라도 TEE 내에서 처리되는 데이터에 대한 가시성을 확보할 수 있습니다.

요약 보고서

요약 보고서 노이즈를 추가하여 수집한 데이터를 확인할 수 있습니다. 다음과 같이 요청할 수 있습니다. 요약 보고서를 생성합니다.

요약 보고서에는 JSON 사전 스타일의 키-값 쌍 집합이 포함됩니다. 각 쌍에 포함된 항목:

bucket: 바이너리 숫자 문자열로 된 집계 키입니다. 만약 사용된 집계 키는 '123'이고 버킷은 '1111011'입니다.
value: 지정된 측정 목표의 요약 값으로, 다음에서 합산됩니다. 노이즈가 추가된 집계 가능한 모든 보고서

예를 들면 다음과 같습니다.

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

노이즈 및 확장

사용자 개인 정보를 보호하기 위해 집계 서비스는 각 코드에 한 번씩 노이즈를 추가합니다. 요약 보고서가 요청될 때마다 이 값을 노이즈 값은 라플라스 확률에서 무작위로 추출 배포와 관련이 있습니다 작업 중에 노이즈가 추가되는 방식을 직접 제어할 수 없으므로 이러한 결과에 영향을 줄 수 있습니다. 노이즈를 최소화합니다

노이즈 분포는 집계 가능한 모든 노이즈의 합계와 관계없이 동일합니다. 값으로 사용됩니다. 따라서 집계 가능한 값이 클수록 노이즈에 미치는 영향이 적습니다. 있습니다.

예를 들어 노이즈 분포의 표준 편차가 100이라고 가정해 보겠습니다. 0에 중심을 둡니다. 수집된 집계 가능한 보고서 값 (또는 '집계 가능한 값')이 200에 불과한 경우 노이즈의 표준 편차는 집계된 값의 50% 에 해당합니다. 그러나 집계 가능한 값이 20,000이면 노이즈의 표준 편차는 집계된 값의 0.5% 에 불과합니다. 따라서 집계 가능한 값이 20,000이면 신호 대 잡음비가 훨씬 더 높습니다.

따라서 집계 가능한 값에 배율을 곱하면 줄일 수 있습니다. 배율은 특정 값을 집계 가능한 값입니다.

더 큰 배율을 선택하여 값을 확장하면 상대적 있습니다. 하지만 이렇게 하면 모든 버킷의 모든 기여도 합계가 발생합니다. 후원 예산 한도에 더 빨리 도달합니다. 다음과 같이 값을 축소합니다. 작은 배율 상수를 선택하면 상대 노이즈는 증가하지만 예산 한도에 도달할 위험이 있습니다.

적절한 배율을 계산하려면 기여 예산을 다음과 같이 나눕니다. 모든 키에서 집계 가능한 값의 최대 합계입니다.

자세한 내용은 기여 예산 문서 를 참조하세요.

참여 및 의견 공유

Private Aggregation API는 현재 논의 중이며 다음 기간 동안 변경될 수 있습니다. 생각해 보세요 이 API를 사용해 보고 의견이 있으면 언제든지 알려 주세요.

GitHub: 설명, 질문을 제기하고 논의합니다. * 개발자 지원: 개인 정보 보호 샌드박스 개발자 지원 저장소를 참조하세요. * Shared Storage API에 참여 그룹 및 Protected Audience API 그룹 비공개 집계와 관련된 최신 공지사항을 확인하세요.