1. Pré-requisitos
Alguns pré-requisitos são necessários para realizar este codelab. Cada requisito é marcado adequadamente, seja para "Teste local" ou "Serviço de agregação".
1.1. Fazer o download da ferramenta de teste local (teste local)
Para fazer testes locais, é preciso fazer 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 Lambda no GitHub (em inglês). Ele precisa ter o nome LocalTestingTool_{version}.jar.
1.2. Verifique se o JAVA JRE está instalado (serviço de teste e agregação local)
Abra o "Terminal" e use java --version para verificar se a máquina tem o Java ou o openJDK instalado.
Se ele não estiver instalado, você pode fazer o download e a instalação no site Java ou no site do openJDK (links em inglês).
1.3. Fazer o download do conversor de relatórios agregáveis (serviço local de teste e agregação)
Você pode fazer o download de uma cópia do conversor de relatórios agregáveis no repositório do GitHub de demonstrações do Sandbox de privacidade.
1.4. Ativar as APIs do Sandbox de privacidade (serviço de teste e agregação locais)
No navegador, acesse chrome://flags/#privacy-sandbox-ads-apis e ative as APIs do Sandbox de privacidade.
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.
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 o registro e o atestado para o Chrome e o Android.
Para testes locais, o registro pode ser desativado usando uma sinalização do Google Chrome e um switch da CLI.
Para usar a flag do Chrome na nossa demonstração, acesse chrome://flags/#privacy-sandbox-enrollment-overrides e atualize a substituição no seu site. Caso use nosso site de demonstração, não é necessário fazer atualizações.
1.6. Integração do serviço de agregação (serviço de agregação)
O serviço de agregação requer a integração de coordenadores para que eles possam usá-lo. Preencha o formulário de integração do serviço de agregação (link em inglês) fornecendo o endereço do site do relatório, 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 requer o uso de um ambiente de execução confiável que use um ambiente de nuvem. O serviço de agregação é compatível com a Amazon Web Services (AWS) e o Google Cloud (GCP). Este codelab abrange apenas a integração com a AWS.
A AWS fornece 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 CLI da AWS para configurar o ambiente da CLI da AWS.
Se a CLI da AWS for nova, configure-a usando as instruções de configuração da CLI.
1.7.1. Criar bucket S3 da AWS
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. É possível usar o comando da CLI fornecido. Substitua o campo em <> pelas 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. Isso será usado para chamar os endpoints de API createJob e getJob criados na AWS.
1.7.3. Permissões de usuário e grupo da AWS
Para implantar o serviço de agregação na AWS, você precisará conceder determinadas permissões ao usuário usado para implantar o serviço. Neste codelab, confira se o usuário tem acesso de administrador para garantir permissões completas na implantação.
1,8 Terraform (serviço de agregação)
Este codelab usa o Terraform para implantar o serviço de agregação. Confira se o binário do Terraform (em inglês) está instalado no ambiente local.
Faça o download do binário do Terraform (em inglês) no ambiente local.
Depois do download do binário do Terraform, extraia o arquivo e mova o binário do Terraform para /usr/local/bin.
cp <directory>/terraform /usr/local/bin
Verifique se o Terraform está disponível no caminho de classe.
terraform -v
1,9 Postman (para serviço de agregação da AWS)
Neste codelab, use o Postman para gerenciar 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.
Selecione Espaço de trabalho em branco e, em seguida, clique em "Sandbox de privacidade". Selecione Pessoal e clique em Criar.
Faça o download dos arquivos de configuração JSON e de ambiente global do espaço de trabalho pré-configurado.
Use o botão "Import" para importar os arquivos JSON para "My Workspace".
Isso vai criar a coleção do Sandbox de privacidade para você com as solicitações HTTP createJob e getJob.
Atualize a "Chave de acesso" e a "Chave secreta" da AWS na Visualização rápida do ambiente.
Clique em Editar e atualize o "Valor atual" de access_key e secret_key. 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 liberado na sua conta ou execute um processo próprio usando os scripts fornecidos.
2. Codelab de testes locais
Você pode usar a ferramenta de teste local na sua máquina para agregar e gerar relatórios de resumo usando os relatórios de depuração não criptografados.
Etapas do codelab
Etapa 2.1. Acionador de relatório: acione relatórios de agregação particular para coletar relatórios.
Etapa 2.2. Criar relatório agregável de depuração: converta o relatório JSON coletado em um relatório formatado em AVRO.
Essa etapa será semelhante a quando as adtechs coletam os relatórios dos endpoints de relatórios da API e convertem os relatórios JSON em relatórios formatados pela AVRO.
Etapa 2.3. Analisar a chave do intervalo do relatório de depuração: as chaves de intervalo são projetadas por adtechs. Neste codelab, como os buckets são predefinidos, recupere as chaves do bucket conforme fornecidas.
Etapa 2.4. Crie o domínio de saída AVRO: depois que as chaves do intervalo forem recuperadas, crie o arquivo AVRO do domínio de saída.
Etapa 2.5. Criar relatórios de resumo usando a Ferramenta de teste local: use a Ferramenta de teste local para criar relatórios de resumo no ambiente local.
Etapa 2.6. Analise o relatório de resumo: analise o relatório de resumo criado pela Ferramenta de teste local.
2.1. Acionar relatório
Acesse o site de demonstração do Sandbox de privacidade. Isso aciona um relatório de agregação particular. Acesse o relatório em chrome://private-aggregation-internals.
Se o relatório estiver com o status Pendente, selecione-o e clique em Enviar relatórios selecionados.
2.2. Criar relatório agregável de depuração
No 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 da AWS.
Insira o "Corpo do relatório" JSON em um arquivo JSON. Neste exemplo, você pode usar o vim. Mas você pode usar qualquer editor de texto que quiser.
vim report.json
Cole o relatório em report.json e salve o arquivo.
Em seguida, acesse a pasta do relatório e use aggregatable_report_converter.jar para criar o relatório agregável de depuração. Isso vai criar um relatório agregável chamado report.avro no 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 requer dois arquivos ao criar lotes. O relatório agregável 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 de bucket que podem ser recuperadas dos relatórios.
As chaves de bucket são projetadas pelo autor da chamada da API, e demo contém chaves de bucket de exemplo pré-construídas. Como a demonstração ativou o modo de depuração para a agregação particular, é possível analisar o payload de texto não criptografado de depuração no Corpo do relatório para recuperar a chave do bucket. No entanto, nesse caso, a demonstração do Sandbox de privacidade do site cria as chaves do bucket. Como a agregação particular deste site está no modo de depuração, é possível usar o debug_cleartext_payload do Corpo do relatório para conseguir a chave do bucket.
Copie o debug_cleartext_payload do corpo do relatório.
Abra a ferramenta Depurar o decodificador de payload para agregação privada, cole o debug_cleartext_payload na caixa "INPUT" e clique em INPUT.
A página retorna o valor decimal da chave do bucket. Confira a seguir um exemplo de chave de bucket.
2.4. Criar o domínio de saída AVRO
Agora que temos a chave do bucket, copie o valor decimal dela. Continue para criar o output_domain.avro usando a chave do bucket. Substitua
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
O script cria o arquivo output_domain.avro na pasta atual.
2.5. Criar relatórios de resumo usando a Ferramenta de teste local
Para criar os relatórios de resumo, usaremos o LocalTestingTool_{version}.jar que foi transferido por download na Seção 1.1. Use o seguinte comando: Substitua LocalTestingTool_{version}.jar pela versão transferida por download para a LocalTestingTool.
Execute o seguinte comando 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 .
Quando o comando for executado, você vai notar algo semelhante à imagem abaixo. Um relatório output.avro será criado assim que isso for concluído.
2,6 Analise o relatório de resumo
O relatório de resumo criado está no formato AVRO. Para ler isso, é preciso converter o AVRO em um formato JSON. O ideal é que a adtech use o código para converter os relatórios AVRO de volta em JSON.
No nosso codelab, vamos usar a ferramenta aggregatable_report_converter.jar fornecida para converter o relatório AVRO de volta para JSON.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
Com isso, será retornado um relatório semelhante à imagem a seguir. Com um relatório output.json criado no mesmo diretório.
Abra o arquivo JSON em um editor de sua preferência para analisar o relatório de resumo.
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: implante o serviço de agregação na AWS
Etapa 3.1. Clone o repositório de serviços de agregação
Etapa 3.2. Faça o download das dependências pré-criadas.
Etapa 3.3 Criar um ambiente de desenvolvimento.
Etapa 3.4 Implantar serviço de agregação
3.1. Clone o repositório do serviço de agregação
No seu ambiente local, clone o repositório do serviço de agregação do GitHub.
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 no repositório e a pasta correspondente na nuvem. Se o cloud_provider for AWS, você poderá acessar
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 input editar o arquivo.
vim main.tf
Remova a marca de comentário do código na caixa vermelha removendo a # e atualizando os nomes de bucket e chave.
Para o arquivo main.tf do AWS:
O código sem marca de comentário ficará assim:
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
Quando as atualizações forem concluídas, salve-as e saia do editor pressionando esc -> :wq!. Assim, as atualizações feitas em main.tf serão salvas.
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 que input edite o arquivo.
vim dev.auto.tfvars
Atualize os campos na caixa vermelha abaixo da imagem com os parâmetros ARN corretos da AWS fornecidos durante a integração do serviço de agregação, o ambiente e o e-mail de notificação.
Quando as atualizações forem concluídas, pressione esc -> :wq!. O arquivo dev.auto.tfvars será salvo, e ele ficará parecido com a imagem a seguir.
3.4. Implantar serviço de agregação
Para implantar o serviço de agregação, na mesma pasta
terraform init
Isso vai retornar algo semelhante à seguinte imagem:
Depois de inicializar o Terraform, crie o plano de execução. Ele retorna o número de recursos a serem adicionados e outras informações semelhantes à imagem a seguir.
terraform plan
Confira no resumo Plano a seguir. Se essa for uma nova implantação, você verá o número de recursos que serão adicionados, sendo 0 para mudar e 0 para destruir.
Depois disso, é possível aplicar o Terraform.
terraform apply
Quando solicitado a confirmar a execução das ações pelo Terraform, insira um yes no valor.
Quando terraform apply for concluído, 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.
4. Criação de entrada do serviço de agregação
Prossiga com a criação dos relatórios AVRO para lotes 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 em lote.
Etapa 4.1. Relatório do acionador
Etapa 4.2. Coletar relatórios agregáveis
Etapa 4.3 Converter relatórios para AVRO
Etapa 4.4 Criar o domínio de saída AVRO
4.1. Acionar relatório
Acesse o site de demonstração do Sandbox de privacidade. Isso aciona um relatório de agregação particular. Acesse o relatório em chrome://private-aggregation-internals.
Se o relatório estiver com o status Pendente, selecione-o e clique em Enviar relatórios selecionados.
4.2. Coletar relatórios agregáveis
Colete os relatórios agregáveis dos endpoints .well-known da API correspondente.
- Agregação particular
[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 executar a coleta de relatórios manualmente. Na produção, as adtechs precisam coletar e converter os relatórios de maneira programática.
No 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 da AWS.
Insira o "Corpo do relatório" JSON em um arquivo JSON. Neste exemplo, você pode usar o vim. Mas você pode usar qualquer editor de texto que quiser.
vim report.json
Cole o relatório em report.json e salve o arquivo.
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 criar o relatório JSON, acesse a pasta do relatório e use aggregatable_report_converter.jar para ajudar a criar o relatório agregável de depuração. Isso vai criar um relatório agregável chamado report.avro no diretório atual.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. Criar o domínio de saída AVRO
Para criar o arquivo output_domain.avro, você precisa das chaves de bucket que podem ser recuperadas dos relatórios.
As chaves de bucket são projetadas pela adtech, mas, neste caso, a demonstração do Sandbox de privacidade do site cria as chaves de bucket. Como a agregação particular deste site está no modo de depuração, é possível usar o debug_cleartext_payload do Corpo do relatório para conseguir a chave do bucket.
Copie o debug_cleartext_payload do corpo do relatório.
Abra goo.gle/ags-payload-decoder, cole o debug_cleartext_payload na caixa INPUT e clique em INPUT.
A página retorna o valor decimal da chave do bucket. Confira a seguir um exemplo de chave de bucket.
Agora que temos a chave do bucket, crie o output_domain.avro. Substitua
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 que os relatórios do AVRO (da seção 3.2.3) e o domínio de saída (da seção 3.2.4) forem criados, mova os relatórios e o domínio de saída para os buckets do S3 de relatórios.
Se você tiver a CLI da AWS configurada no seu ambiente local, use os seguintes comandos para copiar os relatórios para o bucket e a pasta de relatórios correspondentes do S3.
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
No terraform apply, você retorna o create_job_endpoint, o get_job_endpoint e a frontend_api_id. Copie o frontend_api_id e coloque-o na variável global postman frontend_api_id que você configurou na seção de pré-requisitos 1.9.
Etapa 5. Uso do serviço de agregação: use essa API para criar e analisar relatórios de resumo.
Etapa 5.1 Como usar o endpoint createJob para fazer lotes
Etapa 5.2. Como usar o endpoint do getJob para recuperar o status do lote
Etapa 5.3. Revisão do relatório de resumo
5.1. Como usar o endpoint createJob para fazer lotes
No Postman, abra a coleção Sandbox de privacidade e selecione createJob.
Selecione Corpo e bruto para colocar o payload da solicitação.
O esquema de payload createJob está disponível no github e é semelhante ao seguinte. Substitua os <> pelos campos apropriados.
{
"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>",
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
Ao clicar em Send, a tarefa será criada com o job_request_id. Você vai receber uma resposta HTTP 202 quando a solicitação for aceita pelo serviço de agregação. Outro código de retorno possível pode ser encontrado em códigos de resposta HTTP
5.2. Como usar o endpoint getJob para recuperar o status do lote
Para verificar o status da solicitação do job, use o endpoint getJob. Selecione "getJob" na coleção "Sandbox de privacidade".
Em "Params", atualize o valor de job_request_id para o job_request_id que foi enviado na solicitação createJob.
O resultado de getJob precisa retornar o status da solicitação de job com um status HTTP 200. A solicitação "Body" contém as informações necessárias, como job_status, return_message e error_messages (se o job tiver um erro).
Como o site do relatório de demonstração gerado é diferente do site integrado no ID da AWS, você pode receber uma resposta com return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR. Isso é normal, já que o site de origem dos relatórios não corresponde ao site integrado ao ID da AWS.
{
"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_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-news.dev"
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Revisão do relatório de resumo
Quando você receber o relatório do resumo no bucket de saída do S3, poderá fazer o download dele para o ambiente local. Os relatórios de resumo estão no formato AVRO e podem ser novamente convertidos 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 é semelhante à imagem a seguir.
Caso sua solicitação createJob inclua debug_run como true, você poderá receber o relatório de resumo na pasta de depuração localizada em output_data_blob_prefix. O relatório está no formato AVRO e pode ser convertido usando o comando anterior em um JSON.
O relatório contém a chave do intervalo, a métrica sem ruído e o ruído que é adicionado à métrica sem ruído para formar o relatório de resumo. O relatório é semelhante à imagem a seguir.
As anotações também contêm in_reports e in_domain, o que significa que:
- in_reports - a chave do bucket está disponível nos relatórios agregáveis.
- in_domain - a chave do bucket está disponível dentro do arquivo AVRO output_domain.