Trabalhar com serviço de agregação na AWS

1. Pré-requisitos

Para executar este codelab, é preciso cumprir alguns pré-requisitos. Cada requisito é marcado conforme a necessidade para "Teste local" ou "Serviço de agregação".

1.1. Fazer o download da Ferramenta de teste local

Para realizar testes locais, é necessário 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 do Lambda no GitHub. Ele precisa ter o nome 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 o Java ou o openJDK instalado.

verificação da versão do java jre usando java\n--version

Se ele não estiver instalado, faça o download e instale-o no site do Java ou no site do openJDK (link em inglês).

1.3. Baixar o conversor de relatórios agregáveis (teste local e serviço de agregação)

Faça o download de uma cópia do conversor de relatórios agregáveis no repositório do GitHub para demonstrações do Sandbox de privacidade (link em inglês).

1.4. Ativar as APIs de privacidade de anúncios (teste local e serviço de 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ção de cookies de terceiros

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, confira se você concluiu o registro e o atestado para o Chrome e o Android.

Para testes locais, o registro pode ser desativado usando uma sinalização do Chrome e um interruptor da CLI.

Para usar a sinalização do Chrome na nossa demonstração, acesse chrome://flags/#privacy-sandbox-enrollment-overrides e atualize a substituição no seu site. Se você for usar nosso site de demonstração, não precisa fazer nenhuma atualização.

substituição de inscrição do Sandbox de privacidade chromeflag

1.6. Integração do serviço de agregação (serviço de agregação)

O serviço de agregação requer integração aos coordenadores para que eles possam usar o serviço. 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 usa um ambiente em nuvem. O serviço de agregação é compatível com Amazon Web Services (AWS) e Google Cloud (GCP). Este codelab aborda 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 o ambiente da AWS CLI.

Se a CLI da AWS for nova, configure a CLI da AWS usando as instruções de configuração da CLI.

1.7.1. Criar o bucket S3 da AWS

Crie um bucket S3 da AWS 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 com o guia da AWS. Ele 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 na implantação do serviço. Para este codelab, o usuário precisa ter 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 está instalado no seu ambiente local.

Faça o download do binário do Terraform para o ambiente local.

Depois de fazer o download do binário do Terraform, extraia o arquivo e mova-o 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 AWS)

Neste codelab, use o Postman para gerenciar as solicitações.

Para criar um espaço de trabalho, acesse Espaços de trabalho. na parte de cima da tela e selecione Criar espaço de trabalho.

Postmanworkspace

Selecione Espaço de trabalho em branco, clique em "Próxima" e nomeie-o como Sandbox de privacidade. Selecione Pessoal. e clique em Criar.

Faça o download dos arquivos pré-configurados da configuração JSON e do ambiente global do espaço de trabalho.

Importe os arquivos JSON para o Meu espaço de trabalho. usando a opção "Importar" .

importar arquivos JSON do postman

Isso vai criar a coleção do Sandbox de privacidade com as solicitações HTTP createJob e getJob.

coleção importada de postman

Atualize a "Chave de acesso" da AWS e "Secret Key" usando a "Visão rápida do ambiente".

visão rápida do ambiente postman

Clique em Editar. e atualize o "Valor atual" de "access_key" e secret_key. Observe que 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 na sua conta ou faça uma criação automática usando os scripts fornecidos.

globalvariables do Postman

postman editar globalvariables

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 com os relatórios de depuração não criptografados.

Etapas do codelab

Etapa 2.1. Acionar relatório: acione o relatório de agregação privada para coletar o relatório.

Etapa 2.2. Criar relatório agregável de depuração: converta o relatório JSON coletado em um formato formatado pelo 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 no formato 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 de bucket conforme fornecidas.

Etapa 2.4. Crie o domínio de saída AVRO: depois que as chaves de intervalo forem recuperadas, crie o arquivo AVRO do domínio de saída.

Etapa 2.5. Crie relatórios de resumo usando a Ferramenta de teste local: use essa ferramenta para gerar relatórios de resumo no ambiente local.

Etapa 2.6. Analisar o relatório de resumo: consulte 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. Confira o relatório em chrome://private-aggregation-internals.

agregado interno privado do chrome

Se o relatório estiver como Pendente status, selecione o relatório e clique em Enviar relatórios selecionados.

enviar relatório de agregação particular

2.2. Criar relatório agregável de depuração

Em chrome://private-aggregation-internals, copie o Corpo do relatório. recebidos no endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

Verifique se em "Corpo do relatório" o aggregation_coordinator_origin contém https://publickeyservice.msmt.aws.privacysandboxservices.com, o que significa que é um relatório agregável da AWS.

relatório de agregação particular

Insira o "Corpo do relatório" JSON. em um arquivo JSON. Neste exemplo, você pode usar o vim. Mas você pode usar o editor de texto que quiser.

vim report.json

Cole o relatório em report.json e salve o arquivo.

arquivo JSON de relatório

Depois disso, navegue até a pasta do relatório 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 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 em 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 a demonstração contém chaves de bucket de exemplo 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, nesse caso, a demonstração do Sandbox de privacidade do site cria as chaves do bucket. Como a agregação particular desse 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.

depurar payload de texto não criptografado do corpo do relatório

Abra a ferramenta Decodificador de payload de depuração para Agregação Privada e cole o debug_cleartext_payload no campo "ENTRADA". e clique em "Decodificar".

payloaddecoder

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 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 pela chave do bucket recuperada.

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

Usaremos o LocalTestingTool_{version}.jar que foi baixado 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 a seguir para gerar um relatório de resumo no ambiente de desenvolvimento local:

java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .

Você verá algo semelhante à imagem abaixo quando o comando for executado. Um relatório output.avro será criado assim que esse processo for concluído.

avrofile do relatório de resumo de teste local

2,6 Analisar o relatório de resumo

O relatório de resumo que é criado está no formato AVRO. Para conseguir ler isso, é necessário converter o arquivo do AVRO para o formato JSON. O ideal é que a adtech codifique para converter os relatórios AVRO de volta para JSON.

Para 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

Um relatório semelhante à imagem a seguir será retornado. Junto com 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 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. 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 das 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 da nuvem correspondente. Se o cloud_provider for AWS, será possível prosseguir para /terraform/aws

cd <repository_root>/terraform/aws

Em /terraform/aws, execute download_prebuilt_dependencies.sh.

bash download_prebuilt_dependencies.sh

3.3. Criar um ambiente de desenvolvimento

Crie um ambiente de desenvolvimento em /terraform/aws/environments. Crie uma pasta chamada dev.

mkdir dev

Copie o conteúdo da pasta demo para a pasta dev.

cp -R demo/* dev

Mova-o para a pasta dev.

cd dev

Atualize o arquivo main.tf e pressione i em input para editá-lo.

vim main.tf

Retire a marca de comentário do código na caixa vermelha e atualize os nomes do bucket e da chave.

Para main.tf da AWS:

tffile principal da AWS

O código sem comentário 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 e saia do editor pressionando esc -> :wq!. Isso salva as atualizações de main.tf.

Em seguida, renomeie a example.auto.tfvars como dev.auto.tfvars.

mv example.auto.tfvars dev.auto.tfvars

Atualize o dev.auto.tfvars e pressione i no input para editar o arquivo.

vim dev.auto.tfvars

Atualize os campos na caixa vermelha após 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.

editar dev tfvarsfile automático

Quando as atualizações forem concluídas, pressione esc -> :wq!. O arquivo dev.auto.tfvars será salvo e ficará parecido com a imagem a seguir.

dev auto tfvarsfile atualizado

3.4. Implantar serviço de agregação

Para implantar o serviço de agregação, inicialize o Terraform na mesma pasta /terraform/aws/environments/dev.

terraform init

Isso retornará algo semelhante a esta imagem:

terraforminit

Depois de inicializar o Terraform, crie o plano de execução. Onde retorna o número de recursos a serem adicionados e outras informações adicionais semelhantes à imagem a seguir.

terraform plan

Você pode ver no seguinte "Plano" resumo. Se esta for uma implantação nova, o número de recursos que serão adicionados vai aparecer, com 0 para alteração e 0 para destruição.

terraformplan

Depois disso, é possível aplicar o Terraform.

terraform apply

Quando a confirmação de execução das ações pelo Terraform for solicitada, insira um yes no valor.

terraform applyprompt

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.

terraform applycomplete

4. Criação de entrada do serviço de agregação

Prossiga com a criação dos relatórios do 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 para o serviço de agregação.
Etapa 4.1. Relatório do acionador
Etapa 4.2. Coletar relatórios agregáveis
Etapa 4.3. Converter relatórios para o 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. Confira o relatório em chrome://private-aggregation-internals.

agregado interno privado do chrome

Se o relatório estiver como Pendente status, selecione o relatório e clique em Enviar relatórios selecionados.

enviar relatório de agregação particular

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 coletar os 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. recebidos no endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

Verifique se em "Corpo do relatório" o aggregation_coordinator_origin contém https://publickeyservice.msmt.aws.privacysandboxservices.com, o que significa que é um relatório agregável da AWS.

relatório de agregação particular

Insira o "Corpo do relatório" JSON. em um arquivo JSON. Neste exemplo, você pode usar o vim. Mas você pode usar o editor de texto que quiser.

vim report.json

Cole o relatório em report.json e salve o arquivo.

arquivo JSON de 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 para o formato de relatório AVRO. Depois de gerar o relatório JSON, 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 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. No entanto, nesse caso, a demonstração do Sandbox de privacidade do site cria as chaves do bucket. Como a agregação particular desse 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.

depurar payload de texto não criptografado do corpo do relatório

Abra goo.gle/ags-payload-decoder e cole o debug_cleartext_payload na INPUT. e clique em "Decodificar".

payloaddecoder

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. Substitua pela chave do bucket recuperada.

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 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 de relatórios do S3.

Se você tiver a CLI da AWS configurada no ambiente local, use os comandos a seguir para copiar os relatórios para o bucket do S3 e a pasta de relatórios 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

No terraform apply, são retornados 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 1.9 de pré-requisitos.

Etapa 5: Uso do serviço de agregação: use a API Aggregate Service para criar e analisar relatórios resumidos.
Etapa 5.1. Usar o endpoint createJob para agrupar em lotes
Etapa 5.2. Usar o endpoint getJob para recuperar o status do lote
Etapa 5.3. Revisão do relatório de resumo

5.1. Usando o endpoint createJob para lotes

No Postman, abra o Sandbox de privacidade. coleção e selecione "createJob".

Selecione Corpo. e selecione "raw" para colocar seu payload de solicitação.

postman createJob do corpo 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"
  }
}

Depois de clicar em Send, o job será criado com 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

postman createJob requeststatus

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". no Sandbox de privacidade; coleção.

Em "Params", atualize o valor job_request_id para o job_request_id que foi enviado na solicitação createJob.

postman getJobrequest

O resultado de getJob 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 gerado um erro).

postman getJob requeststatus

Como o site de relatórios do relatório de demonstração gerado é diferente do site integrado no ID da AWS, você pode receber uma resposta com PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code. Isso é normal, pois os relatórios o site da origem de relatórios não corresponde ao site integrado do 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-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. Revisão do relatório de resumo

Depois de receber o relatório de resumo no bucket de saída do S3, faça o download dele para o ambiente local. Os relatórios de resumo estão no formato AVRO e podem ser convertidos de volta para um JSON. Você pode usar aggregatable_report_converter.jar para ler o 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.

summaryreport

Se a solicitação createJob incluir 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 para um JSON.

O relatório contém a chave do bucket, 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 abaixo.

relatório de resumo de depuração

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.