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. Verifique 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.
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 (link em inglês).
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.
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.
1.6. Integração do serviço de agregação (serviço de agregação)
O serviço de agregação exige integração com os coordenadores para poder usar o serviço. 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 as 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 garantir 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.
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 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.
Isso vai criar a coleção do Sandbox de privacidade para você, junto com as solicitações HTTP createJob e getJob.
Atualize a "Chave de acesso" e a "Chave secreta" da AWS pelo 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 a AMI lançada para sua conta ou faça uma autoconstrução usando os scripts fornecidos.
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 de resumo 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 particular 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 fornecidas.
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.
Se a denúncia estiver em Pendente, selecione-a e clique em Enviar relatórios selecionados.
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.
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.
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 privada, você pode analisar o payload de texto não criptografado de depuração do corpo do relatório para recuperar 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.
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.
A página retorna o valor decimal da chave do bucket. Confira a seguir um exemplo de chave de bucket.
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. Substitua
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.
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.
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:
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 forem 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.
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.
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:
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 a seguir o resumo do plano. Se for uma nova implantação, o número de recursos que serão adicionados vai aparecer com 0 para mudar e 0 para destruir.
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.
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.
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.
Se a denúncia estiver em Pendente, selecione-a e clique em Enviar relatórios selecionados.
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 maneira 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.
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.
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.
Abra goo.gle/ags-payload-decoder e cole o debug_cleartext_payload na caixa INPUT e clique em Decode.
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 sua 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 de resumo 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.
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_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>", // Only one of attribution_report_to or reporting_site is required 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.
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.
O resultado da 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).
Como o site de relatórios do relatório de demonstração gerado é 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 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_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>", // Only one of attribution_report_to or reporting_site is required 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.
Se a solicitação createJob incluir debug_run como true, você vai 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.
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.