1. Pré-requisitos
Para realizar este codelab, alguns pré-requisitos são necessários. Cada requisito é marcado de acordo com se ele é necessário para "Testes locais" ou "Serviço de agregação".
1.1. Fazer o download da ferramenta de teste local
O teste local exige o download da ferramenta de teste local. A ferramenta vai gerar relatórios resumidos com base nos relatórios de depuração não criptografados.
A ferramenta de teste local está disponível para download nos arquivos JAR do Lambda no GitHub. Ele precisa ser nomeado como LocalTestingTool_{version}.jar.
1.2. Verificar se o JAVA JRE está instalado (serviço de agregação e teste local)
Abra o Terminal e use java --version para verificar se a máquina tem Java ou openJDK instalado.
Verificação da versão do Java JRE usando "java --version".
Se ele não estiver instalado, faça o download e a instalação no site do Java ou no site do OpenJDK.
1.3. Fazer o download do Aggregatable Report Converter (Serviço de agregação e testes locais)
É possível fazer o download de uma cópia do conversor de relatórios agregáveis no repositório do GitHub das demonstrações do Sandbox de privacidade.
1.4. Ativar as APIs Ad Privacy (serviço de testes locais e agregação)
No navegador, acesse chrome://settings/adPrivacy e ative todas as APIs de privacidade de anúncios.
Verifique se os cookies de terceiros estão ativados.
No navegador, acesse chrome://settings/cookies e selecione Bloquear cookies de terceiros no modo de navegação anônima.
Configurações de cookies de terceiros do Chrome.
1.5. Inscrição na Web e no Android (serviço de agregação)
Para usar as APIs do Sandbox de privacidade em um ambiente de produção, conclua a inscrição e a declaração para o Chrome e o Android.
Para testes locais, a inscrição pode ser desativada usando uma flag do Chrome e um switch da CLI.
Para usar a flag do Chrome para nossa demonstração, acesse chrome://flags/#privacy-sandbox-enrollment-overrides e atualize a substituição com seu site. Se você for usar nosso site de demonstração, não será necessário fazer uma atualização.
Flag do Chrome para substituir a inscrição no Sandbox de privacidade.
1.6. Integração do serviço de agregação (Aggregation Service)
O serviço de agregação exige integração com os coordenadores para poder ser usado. Preencha o formulário de integração do serviço de agregação com o endereço do site de relatórios, o ID da conta da AWS e outras informações.
1.7. Provedor de nuvem (serviço de agregação)
O serviço de agregação exige o uso de um ambiente de execução confiável que usa um ambiente de nuvem. O serviço de agregação tem suporte no Amazon Web Services (AWS) e no Google Cloud (GCP). Este codelab vai abordar apenas a integração com a AWS.
A AWS oferece um ambiente de execução confiável chamado Nitro Enclaves. Verifique se você tem uma conta da AWS e siga as instruções de instalação e atualização da AWS CLI para configurar seu ambiente da AWS CLI.
Se a AWS CLI for nova, você poderá configurá-la usando as instruções de configuração da CLI.
1.7.1. Criar um bucket do AWS S3
Crie um bucket do AWS S3 para armazenar o estado do Terraform e outro bucket do S3 para armazenar seus relatórios e relatórios de resumo. Você pode usar o comando da CLI fornecido. Substitua o campo em <> para variáveis adequadas.
aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1
1.7.2. Criar chave de acesso do usuário
Crie chaves de acesso do usuário usando o guia da AWS. Ele será usado para chamar os endpoints da API createJob e getJob criados na AWS.
1.7.3. Permissões de usuários e grupos da AWS
Para implantar o serviço de agregação na AWS, você precisa conceder determinadas permissões ao usuário usado para implantar o serviço. Para este Codelab, verifique se o usuário tem acesso de administrador para ter certeza de que tem permissões totais na implantação.
1.8. Terraform (serviço de agregação)
Este codelab usa o Terraform para implantar o serviço de agregação. Verifique se o binário do Terraform está instalado no seu ambiente local.
Faça o download do binário do Terraform no seu ambiente local.
Depois que o binário do Terraform for transferido, extraia o arquivo e mova-o para /usr/local/bin.
cp <directory>/terraform /usr/local/bin
Verifique se o Terraform está disponível no classpath.
terraform -v
1.9. Postman (para o serviço de agregação da AWS)
Neste codelab, use o Postman para gerenciamento de solicitações.
Para criar um espaço de trabalho, acesse o item de navegação superior Espaços de trabalho e selecione Criar espaço de trabalho.
Espaço de trabalho do Postman
Selecione Espaço de trabalho em branco, clique em "Próxima" e nomeie como Sandbox de privacidade. Selecione Pessoal e clique em Criar.
Faça o download dos arquivos de configuração JSON e ambiente global do espaço de trabalho pré-configurado.
Importe os arquivos JSON para "Meu espaço de trabalho" usando o botão Importar.
Importar arquivos JSON do Postman.
Isso vai criar a coleção do Sandbox de privacidade para você, junto com as solicitações HTTP createJob e getJob.
Coleção importada do Postman.
Atualize a "Chave de acesso" e a "Chave secreta" da AWS pelo Visualização rápida do ambiente.
Visão geral do ambiente do Postman.
Clique em Editar e atualize o "Valor atual" de access_key e secret_key. O frontend_api_id será fornecido na seção 3.1.4 deste documento. Recomendamos usar a região us-east-1. No entanto, se você quiser implantar em uma região diferente, copie o AMI lançado para sua conta ou faça um autodesenvolvimento usando os scripts fornecidos.
Variáveis globais do Postman. 
O Postman edita variáveis globais.
2. Codelab de testes locais
Você pode usar a ferramenta de teste local na sua máquina para realizar a agregação e gerar relatórios resumidos usando os relatórios de depuração não criptografados.
Etapas do codelab
Etapa 2.1. Acionar relatório: acione os relatórios de agregação privada para coletar o relatório.
Etapa 2.2. Criar um relatório de depuração agregável: converta o relatório JSON coletado em um relatório formatado em AVRO.
Essa etapa é semelhante à coleta de relatórios dos endpoints de relatórios da API pelas adtechs e a conversão dos relatórios JSON em relatórios formatados em AVRO.
Etapa 2.3. Analisar a chave do bucket do relatório de depuração: as chaves de bucket são criadas por adtechs. Neste codelab, como os buckets são predefinidos, extraia as chaves de bucket conforme fornecido.
Etapa 2.4. Criar o AVRO do domínio de saída: depois que as chaves do bucket forem recuperadas, crie o arquivo AVRO do domínio de saída.
Etapa 2,5. Criar relatórios resumidos usando a ferramenta de testes locais: use a ferramenta de testes locais para criar relatórios resumidos no ambiente local.
Etapa 2.6. Analisar o relatório de resumo: analise o relatório de resumo criado pela ferramenta de teste local.
2.1. Relatório de acionadores
Acesse o site da demonstração do Sandbox de privacidade. Isso aciona um relatório de agregação particular. Confira o relatório em chrome://private-aggregation-internals.
Partes internas da agregação particular do Chrome.
Se a denúncia estiver em "Pendente", selecione-a e clique em Enviar relatórios selecionados.
Enviar relatório de agregação particular.
2.2. Criar um relatório agregável de depuração
Em chrome://private-aggregation-internals, copie o "Corpo do relatório" recebido no endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Verifique se, no Corpo do relatório, o aggregation_coordinator_origin contém https://publickeyservice.msmt.aws.privacysandboxservices.com, o que significa que o relatório é agregável pela AWS.
Relatório de agregação particular.
Coloque o JSON "Corpo do relatório" em um arquivo JSON. Neste exemplo, use o vim. Mas você pode usar qualquer editor de texto.
vim report.json
Cole o relatório em report.json e salve o arquivo.
Arquivo JSON do relatório.
Depois disso, navegue até a pasta de relatórios e use aggregatable_report_converter.jar para criar o relatório agregável de depuração. Isso cria um relatório agregável chamado report.avro no seu diretório atual.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. Analisar a chave do bucket do relatório de depuração
O serviço de agregação exige dois arquivos ao agrupar. O relatório que pode ser agregado e o arquivo de domínio de saída. O arquivo de domínio de saída contém as chaves que você quer recuperar dos relatórios agregáveis. Para criar o arquivo output_domain.avro, você precisa das chaves do bucket que podem ser recuperadas dos relatórios.
As chaves de bucket são projetadas pelo autor da chamada da API, e a demonstração contém exemplos de chaves de bucket pré-construídas. Como a demonstração ativou o modo de depuração para a agregação particular, você pode analisar o payload de texto não criptografado de depuração do corpo do relatório para extrair a chave do bucket. No entanto, neste caso, a demonstração do sandbox de privacidade do site cria as chaves do bucket. Como a agregação privada para esse site está no modo de depuração, use o debug_cleartext_payload do Corpo do relatório para acessar a chave do bucket.
Copie o debug_cleartext_payload do corpo do relatório.
Depura o payload de texto simples do corpo do relatório.
Abra a ferramenta Decodificador de payload de depuração para agregação privada e cole o debug_cleartext_payload na caixa INPUT e clique em Decode.
Decodificador de payload.
A página retorna o valor decimal da chave do bucket. Confira a seguir um exemplo de chave de bucket.
Resultado do decodificador de payload.
2.4. Criar o AVRO do domínio de saída
Agora que temos a chave do bucket, copie o valor decimal dela. Crie o output_domain.avro usando a chave do bucket. Verifique se você substituiu
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
O script cria o arquivo output_domain.avro na sua pasta atual.
2.5. Criar relatórios de resumo usando a ferramenta de teste local
Vamos usar o LocalTestingTool_{version}.jar que foi feito o download na seção 1.1 para criar os relatórios de resumo. Use o comando a seguir. Substitua LocalTestingTool_{version}.jar pela versão transferida por download para a LocalTestingTool.
Execute o comando abaixo para gerar um relatório de resumo no seu ambiente de desenvolvimento local:
java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .
Você vai encontrar algo parecido com a imagem a seguir quando o comando for executado. Um relatório output.avro é criado quando isso é concluído.
Arquivo avro do relatório de resumo do teste local.
2.6. Analisar o relatório resumido
O relatório de resumo criado é no formato AVRO. Para ler isso, você precisa converter o formato AVRO em JSON. O ideal é que a adtech codifique para converter relatórios AVRO em JSON.
Para o codelab, vamos usar a ferramenta aggregatable_report_converter.jar fornecida para converter o relatório AVRO em JSON.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
Isso vai retornar um relatório semelhante à imagem abaixo. Além de um relatório output.json criado no mesmo diretório.
Arquivo avro de resumo convertido em JSON.
Abra o arquivo JSON em um editor de sua preferência para analisar o relatório resumido.
3. Implantação do serviço de agregação
Para implantar o serviço de agregação, siga estas etapas:
Etapa 3: Implantação do serviço de agregação: implantar o serviço de agregação na AWS
Etapa 3.1. Clone o repositório do serviço de agregação
Etapa 3.2. Fazer o download de dependências pré-criadas
Etapa 3.3. Criar um ambiente de desenvolvimento
Etapa 3.4. Implantar o serviço de agregação
3.1. Clonar o repositório do serviço de agregação
No seu ambiente local, clone o repositório do GitHub do serviço de agregação.
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. Fazer o download de dependências pré-criadas
Depois de clonar o repositório do serviço de agregação, acesse a pasta do Terraform do repositório e a pasta correspondente na nuvem. Se o cloud_provider for AWS, prossiga para
cd <repository_root>/terraform/aws
Em download_prebuilt_dependencies.sh.
bash download_prebuilt_dependencies.sh
3.3. Criar um ambiente de desenvolvimento
Crie um ambiente de desenvolvimento em dev.
mkdir dev
Copie o conteúdo da pasta demo para a pasta dev.
cp -R demo/* dev
Mova para a pasta dev.
cd dev
Atualize o arquivo main.tf e pressione i para que o input edite o arquivo.
vim main.tf
Remova o caractere # para remover a marca de comentário do código na caixa vermelha e atualize os nomes do bucket e da chave.
Para o main.tf da AWS:
Arquivo principal do AWS.
O código sem comentários vai ficar assim:
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
Quando as atualizações estiverem concluídas, salve as atualizações e saia do editor pressionando esc -> :wq!. Isso salva as atualizações em main.tf.
Em seguida, renomeie example.auto.tfvars como dev.auto.tfvars.
mv example.auto.tfvars dev.auto.tfvars
Atualize dev.auto.tfvars e pressione i para input editar o arquivo.
vim dev.auto.tfvars
Atualize os campos na caixa vermelha conforme a imagem com os parâmetros corretos do ARN da AWS fornecidos durante a integração do serviço de agregação, o ambiente e o e-mail de notificação.
Edite o arquivo de auto tfvars do desenvolvedor.
Quando as atualizações forem concluídas, pressione esc -> :wq!. O arquivo dev.auto.tfvars será salvo e vai ficar parecido com a imagem abaixo.
Atualização do arquivo detfvars automático de desenvolvimento.
3.4. Implantar o serviço de agregação
Para implantar o serviço de agregação, na mesma pasta
terraform init
Isso vai retornar algo semelhante à imagem abaixo:
Terraform init.
Depois que o Terraform for inicializado, crie o plano de execução do Terraform. Onde ele retorna o número de recursos a serem adicionados e outras informações semelhantes à imagem abaixo.
terraform plan
Confira abaixo o resumo do plano. Se for uma nova implantação, o número de recursos que serão adicionados vai aparecer com 0 para "change" e 0 para "destroy".
plano do Terraform.
Depois disso, você pode aplicar o Terraform.
terraform apply
Quando o Terraform solicitar a confirmação da execução das ações, insira um yes no valor.
Comando Terraform apply.
Quando terraform apply terminar, os seguintes endpoints para createJob e getJob serão retornados. O frontend_api_id que você precisa atualizar no Postman na seção 1.9 também é retornado.
O terraform apply foi concluído.
4. Criação de entrada de serviço de agregação
Crie os relatórios AVRO para lote no serviço de agregação.
Etapa 4: Criação de entrada do serviço de agregação: crie os relatórios do serviço de agregação que são agrupados para o serviço de agregação.
Etapa 4.1. Acionar relatório
Etapa 4.2. Coletar relatórios agregáveis
Etapa 4.3. Converter relatórios para AVRO
Etapa 4.4 Criar o AVRO do domínio de saída
4.1. Relatório de acionadores
Acesse o site da demonstração do Sandbox de privacidade. Isso aciona um relatório de agregação particular. Confira o relatório em chrome://private-aggregation-internals.
Partes internas da agregação particular do Chrome.
Se a denúncia estiver em "Pendente", selecione-a e clique em Enviar relatórios selecionados. "
Enviar relatório de agregação particular.
4.2. Coletar relatórios agregáveis
Colete relatórios agregáveis dos endpoints .well-known da API correspondente.
- Private Aggregation
[reporting-origin] /.well-known/private-aggregation/report-shared-storage - Relatórios de atribuição: relatório de resumo
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
Neste codelab, você vai realizar a coleta de relatórios manualmente. Na produção, as adtechs precisam coletar e converter os relatórios de forma programática.
Em chrome://private-aggregation-internals, copie o "Corpo do relatório" recebido no endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Verifique se, no Corpo do relatório, o aggregation_coordinator_origin contém https://publickeyservice.msmt.aws.privacysandboxservices.com, o que significa que o relatório é agregável pela AWS.
Relatório de agregação particular.
Coloque o JSON "Corpo do relatório" em um arquivo JSON. Neste exemplo, use o vim. Mas você pode usar qualquer editor de texto.
vim report.json
Cole o relatório em report.json e salve o arquivo.
Arquivo JSON do relatório.
4.3. Converter relatórios para AVRO
Os relatórios recebidos dos endpoints .well-known estão no formato JSON e precisam ser convertidos no formato de relatório AVRO. Depois de ter o relatório JSON, navegue até a pasta de relatórios e use aggregatable_report_converter.jar para ajudar a criar o relatório agregável de depuração. Isso cria um relatório agregável chamado report.avro no seu diretório atual.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. Criar o AVRO do domínio de saída
Para criar o arquivo output_domain.avro, você precisa das chaves do bucket que podem ser recuperadas dos relatórios.
As chaves de bucket são projetadas pela adtech. No entanto, neste caso, a demonstração do Sandbox de privacidade do site cria as chaves de bucket. Como a agregação privada para esse site está no modo de depuração, use o debug_cleartext_payload do Corpo do relatório para acessar a chave do bucket.
Copie o debug_cleartext_payload do corpo do relatório.
Depura o payload de texto simples do corpo do relatório.
Abra goo.gle/ags-payload-decoder e cole o debug_cleartext_payload na caixa INPUT e clique em Decode.
Decodificador de payload.
A página retorna o valor decimal da chave do bucket. Confira a seguir um exemplo de chave de bucket.
Resultado do decodificador de payload.
Agora que temos a chave do bucket, crie o output_domain.avro. Verifique se você substituiu
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
O script cria o arquivo output_domain.avro na pasta atual.
4.5. Mover relatórios para o bucket da AWS
Depois de criar os relatórios do AVRO (seção 3.2.3) e o domínio de saída (seção 3.2.4), mova os relatórios e o domínio de saída para os buckets do S3 de relatórios.
Se você tiver a configuração da AWS CLI no seu ambiente local, use os comandos a seguir para copiar os relatórios para o bucket e a pasta de relatórios do S3 correspondentes.
aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/
5. Uso do serviço de agregação
A terraform apply retorna create_job_endpoint, get_job_endpoint e frontend_api_id. Copie o frontend_api_id e coloque-o na variável global frontend_api_id do Postman que você configurou na seção de pré-requisitos 1.9.
Etapa 5: Uso do serviço de agregação: use a API do serviço de agregação para criar relatórios resumidos e analisar esses relatórios.
Etapa 5.1. Como usar o endpoint createJob para processar em lote
Etapa 5.2. Como usar o endpoint getJob para recuperar o status do lote
Etapa 5.3. Como analisar o relatório resumido
5.1. Como usar o endpoint createJob para lotes
No Postman, abra a coleção Privacy Sandbox e selecione createJob.
Selecione "Body" e "raw" para colocar o payload da solicitação.
corpo da solicitação postman createJob
O esquema de payload createJob está disponível no github e é semelhante ao seguinte. Substitua <> pelos campos apropriados.
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_blob_prefixes": [
"<report_folder>/<report_name-1>/",
"<report_folder>/<report_name-2>/",
"<report_folder>/<report_name>.avro"
], // Mutually exclusive to input_data_blob_prefix as of v2.11.0
"input_data_bucket_name": "<bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
Ao clicar em Enviar, o job é criado com o job_request_id. Você vai receber uma resposta HTTP 202 quando a solicitação for aceita pelo serviço de agregação. Outros códigos de retorno possíveis podem ser encontrados em Códigos de resposta HTTP.
status da solicitação de criação de job do postman
5.2. Como usar o endpoint getJob para recuperar o status do lote
Para verificar o status da solicitação de job, use o endpoint getJob. Selecione getJob na coleção Sandbox de privacidade.
Em Params, atualize o valor job_request_id para o job_request_id enviado na solicitação createJob.
solicitação postman getJob
O resultado do getJob deve retornar o status da solicitação de job com um status HTTP de 200. O corpo da solicitação contém as informações necessárias, como job_status, return_message e error_messages (se o job tiver falhado).
status da solicitação de getJob do postman
Como o site de relatórios da demonstração gerada é diferente do site integrado no seu AWS ID, você pode receber uma resposta com PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code. Isso é normal, já que o site de origem dos relatórios não corresponde ao site de relatórios integrado ao AWS ID.
{
"job_status": "FINISHED",
"request_received_at": "2023-12-07T22:50:58.830956Z",
"request_updated_at": "2023-12-07T22:51:10.526326456Z",
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
"<report_folder>/<report_name-1>/",
"<report_folder>/<report_name-2>/",
"<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>",
"postback_url": "",
"result_info": {
"return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-12-07T22:51:10.517730898Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"attribution_report_to": "https://privacy-sandbox-demos-dsp.dev",
"reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Como analisar o relatório resumido
Depois de receber o relatório de resumo no bucket do S3 de saída, você pode fazer o download dele no seu ambiente local. Os relatórios de resumo estão no formato AVRO e podem ser convertidos de volta em JSON. Você pode usar aggregatable_report_converter.jar para ler seu relatório usando o comando a seguir.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
Isso retorna um JSON de valores agregados de cada chave de bucket que se parece com a imagem a seguir.
Relatório de resumo.
Se a solicitação createJob incluir debug_run como true, você poderá receber o relatório de resumo na pasta de depuração localizada no output_data_blob_prefix. O relatório está no formato AVRO e pode ser convertido em JSON usando o comando anterior.
O relatório contém a chave do bucket, a métrica sem ruído e o ruído adicionado à métrica sem ruído para formar o relatório resumido. O relatório é semelhante à imagem a seguir.
Relatório de resumo da depuração.
As anotações também contêm in_reports e in_domain, o que significa:
- in_reports: a chave do bucket está disponível nos relatórios agregáveis.
- in_domain: a chave do bucket está disponível no arquivo AVRO output_domain.