Trabaja con el servicio de agregación en AWS

1. Requisitos previos

Para realizar este codelab, se requieren algunos requisitos previos. Cada requisito se marca según corresponda para las "Pruebas locales" o el "Servicio de agregación".

1.1. Cómo descargar la Herramienta de pruebas locales (pruebas locales)

Para las pruebas locales, debes descargar la herramienta de pruebas locales. La herramienta generará informes de resumen a partir de los informes de depuración sin encriptar.

La herramienta de pruebas locales está disponible para descargar en los archivos JAR de Lambda en GitHub. Debe tener el nombre LocalTestingTool_{version}.jar.

1.2. Asegúrate de que JAVA JRE esté instalado (servicio de agregación y pruebas locales)

Abre "Terminal" y usa java --version para verificar si tu máquina tiene Java o openJDK instalados.

Si no está instalada, puedes descargarla e instalarla desde el sitio de Java o el sitio de openJDK.

1.3. Descarga el convertidor de informes agregables (servicio de agregación y pruebas locales)

Puedes descargar una copia del conversor de informes agregables desde el repositorio de GitHub de demostraciones de Privacy Sandbox.

1.4. Habilita las APIs de privacidad en los anuncios (prueba local y servicio de agregación)

En tu navegador, ve a chrome://settings/adPrivacy y habilita todas las APIs de privacidad en los anuncios.

Asegúrate de que las cookies de terceros estén habilitadas.

En el navegador, ve a chrome://settings/cookies y selecciona "Bloquear cookies de terceros en modo Incógnito".

1.5. Inscripción web y de Android (servicio de agregación)

Para usar las APIs de Privacy Sandbox en un entorno de producción, asegúrate de haber completado la inscripción y la certificación para Chrome y Android.

Para las pruebas locales, la inscripción se puede inhabilitar con una marca de Chrome y un interruptor de la CLI.

Para usar la función experimental de Chrome en nuestra demostración, ve a chrome://flags/#privacy-sandbox-enrollment-overrides y actualiza la anulación con tu sitio. Si vas a usar nuestro sitio de demostración, no es necesario que actualices la app.

1.6. Integración del servicio de agregación (servicio de agregación)

El servicio de agregación requiere integrarse a los coordinadores para que puedan usarlo. Completa el formulario de integración del servicio de agregación proporcionando la dirección de tu sitio de informes, el ID de la cuenta de AWS y otra información.

1.7. Proveedor de servicios en la nube (servicio de agregación)

El servicio de agregación requiere el uso de un entorno de ejecución confiable que use un entorno de nube. El servicio de agregación es compatible con Amazon Web Services (AWS) y Google Cloud (GCP). Este codelab solo abarcará la integración con AWS.

AWS proporciona un entorno de ejecución confiable llamado Nitro Enclaves. Asegúrate de tener una cuenta de AWS y sigue las instrucciones de instalación y actualización de AWS CLI para configurar tu entorno.

Si tu CLI de AWS es nueva, puedes configurarla mediante las instrucciones de configuración de la CLI.

1.7.1. Crea un bucket de AWS S3

Crea un bucket de AWS S3 para almacenar el estado de Terraform y otro bucket S3 para almacenar tus informes de resumen y tus informes. Puedes usar el comando de la CLI proporcionado. Reemplaza el campo en <> por las variables apropiadas.

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. Crear clave de acceso de usuario

Crea claves de acceso para los usuarios con la guía de AWS. Se usará para llamar a los extremos de la API createJob y getJob creados en AWS.

1.7.3. Permisos de usuarios y grupos de AWS

Para implementar el servicio de agregación en AWS, deberás proporcionar ciertos permisos al usuario que se usan para implementar el servicio. Para este codelab, asegúrate de que el usuario tenga acceso de administrador para garantizar permisos completos en la implementación.

1.8. Terraform (servicio de agregación)

En este codelab, se usa Terraform para implementar el servicio de agregación. Asegúrate de que el objeto binario de Terraform esté instalado en tu entorno local.

Descarga el objeto binario de Terraform en tu entorno local.

Una vez que se descargue el objeto binario de Terraform, extrae el archivo y muévelo a /usr/local/bin.

cp <directory>/terraform /usr/local/bin

Asegúrate de que Terraform esté disponible en la ruta de clase.

terraform -v

1.9 Postman (para AWS de servicio de agregación)

En este codelab, usa Postman para la administración de solicitudes.

Para crear uno, ve al elemento de navegación superior “Lugares de trabajo” y selecciona “Crear lugar de trabajo”.

Seleccione "Blank workspace", haga clic en Siguiente y asígnele el nombre "Privacy Sandbox". Selecciona "Personal" y haz clic en "Crear".

Descarga los archivos preconfigurados de configuración JSON y del entorno global del lugar de trabajo.

Importa los archivos JSON a “Mi espacio de trabajo” con el botón “Importar”.

Esto creará la colección de Privacy Sandbox por ti junto con las solicitudes HTTP createJob y getJob.

Actualiza la "Clave de acceso" y la "Clave secreta" de AWS a través de la "Vista rápida del entorno".

Haz clic en "Editar" y actualiza el "Valor actual" de "access_key" y "secret_key". Ten en cuenta que frontend_api_id se proporcionará en la sección 3.1.4 de este documento. Y recomendamos usar la región us-east-1. Sin embargo, si deseas realizar la implementación en una región diferente, asegúrate de copiar la AMI lanzada en tu cuenta o realizar una compilación propia con las secuencias de comandos proporcionadas.

2. Codelab de pruebas locales

Puedes usar la herramienta de pruebas local en tu máquina para realizar agregaciones y generar informes de resumen con los informes de depuración sin encriptar.

Pasos del codelab

Paso 2.1: Activar informe: Activa los informes de agregación privada para poder recopilar el informe.

Paso 2.2: Crear informe agregable de depuración: Convierte el informe JSON recopilado en un informe con formato AVRO.
Este paso será similar a cuando las tecnologías publicitarias recopilan los informes de los extremos de informes de la API y convierten los informes JSON en informes con formato AVRO.

Paso 2.3: Analiza la clave de bucket del informe de depuración: Las tecnologías publicitarias diseñan las claves de bucket. En este codelab, debido a que los buckets están predefinidos, recupera las claves del bucket como se proporcionan.

Paso 2.4: Crea el dominio de salida AVRO: Una vez que se recuperen las claves del bucket, crea el archivo AVRO del dominio de salida.

Paso 2.5: Crear informes de resumen con la herramienta de prueba local: Usa esta herramienta para poder crear informes de resumen en el entorno local.

Paso 2.6: Revisar el informe de resumen: Revisa el informe de resumen que crea la Herramienta de pruebas locales.

2.1. Activar informe

Ve al sitio de demostración de Privacy Sandbox. Esto activa un informe de agregación privado. Puedes ver el informe en chrome://private-aggregation-internals.

Si el estado de tu informe es "Pendiente", puedes seleccionarlo y hacer clic en "Enviar informes seleccionados".

2.2. Crea un informe agregable de depuración

En chrome://private-aggregation-internals, copia el "Cuerpo del informe" que recibiste en el extremo [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

Asegúrate de que en el "Cuerpo del informe", el aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, lo que significa que el informe es agregable de AWS.

Coloca el "cuerpo del informe" en JSON en un archivo JSON. En este ejemplo, puedes usar vim. Pero puedes usar el editor de texto que desees.

vim report.json

Pega el informe en report.json y guarda el archivo.

Una vez que tengas eso, navega a tu carpeta de informes y usa aggregatable_report_converter.jar para crear el informe agregable de depuración. Esto crea un informe agregable llamado report.avro en tu directorio actual.

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json \
 --debug

2.3. Analiza la clave del bucket del informe de depuración

El servicio de agregación requiere dos archivos cuando se procesa en lotes. El informe agregable y el archivo de dominio de salida. El archivo de dominio de salida contiene las claves que deseas recuperar de los informes agregables. Para crear el archivo output_domain.avro, necesitas las claves del bucket que se pueden recuperar a partir de los informes.

El llamador de la API diseña las claves de bucket. La demostración contiene claves de bucket de ejemplo compiladas previamente. Dado que la demostración habilitó el modo de depuración para agregación privada, puedes analizar la carga útil de texto simple de depuración desde el "Cuerpo del informe" para recuperar la clave del bucket. Sin embargo, en este caso, la demostración de Privacy Sandbox del sitio crea las claves del bucket. Dado que la agregación privada de este sitio está en modo de depuración, puedes usar el debug_cleartext_payload del "Cuerpo del informe" para obtener la clave del bucket.

Copia el debug_cleartext_payload del cuerpo del informe.

Abre Decodificador de carga útil de depuración para agregación privada, pega tu debug_cleartext_payload en el cuadro "INPUT" y haz clic en "INPUT".

La página muestra el valor decimal de la clave de bucket. A continuación, se muestra una clave de bucket de muestra.

2.4. Crea el dominio de salida AVRO

Ahora que tenemos la clave de bucket, copia el valor decimal de la clave. Continúa con la creación de output_domain.avro con la clave del bucket. Asegúrate de reemplazar por la clave del bucket que recuperaste.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

La secuencia de comandos crea el archivo output_domain.avro en tu carpeta actual.

2.5. Cómo crear informes de resumen con la Herramienta de pruebas locales

Usaremos el LocalTestingTool_{version}.jar que se descargó en la sección 1.1 para crear los informes de resumen. Usa el siguiente comando: Debes reemplazar LocalTestingTool_{version}.jar por la versión descargada para LocalTestingTool.

Ejecuta el siguiente comando para generar un informe de resumen en tu entorno de desarrollo local:

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

Deberías ver algo similar a la siguiente imagen una vez que se ejecute el comando. Cuando se complete, se creará un informe output.avro.

2.6. Revisa el informe de resumen

El informe de resumen que se crea está en formato AVRO. Para poder leerlo, debes convertirlo de AVRO a un formato JSON. Lo ideal es que la tecnología publicitaria deba codificar para volver a convertir los informes AVRO a JSON.

En nuestro codelab, usaremos la herramienta aggregatable_report_converter.jar proporcionada para volver a convertir el informe AVRO en JSON.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro

Se mostrará un informe similar al de la siguiente imagen. Junto con un informe output.json creado en el mismo directorio.

Abre el archivo JSON en el editor que prefieras para revisar el informe de resumen.

3. Implementación del servicio de agregación

Para implementar el servicio de agregación, sigue estos pasos:

Paso 3: Implementación del servicio de agregación: Implementa el servicio de agregación en AWS
Paso 3.1. Clona el repositorio de servicios de agregación
Paso 3.2: Descarga dependencias compiladas previamente
Paso 3.3: Crea un entorno de desarrollo
Paso 3.4. Implementa el servicio de agregación

3.1. Clona el repositorio del servicio de agregación

En tu entorno local, clona el repositorio de GitHub del servicio de agregación.

git clone https://github.com/privacysandbox/aggregation-service.git

3.2. Cómo descargar dependencias compiladas previamente

Una vez que hayas clonado el repositorio del servicio de agregación, ve a la carpeta de Terraform del repositorio y a la carpeta de Cloud correspondiente. Si tu cloud_provider es AWS, puedes continuar con /terraform/aws

cd <repository_root>/terraform/aws

En /terraform/aws, ejecuta download_prebuilt_dependencies.sh.

bash download_prebuilt_dependencies.sh

3.3. Crea un entorno de desarrollo

Crea un entorno de desarrollo en /terraform/aws/environments. Crea una carpeta llamada dev.

mkdir dev

Copia el contenido de la carpeta demo en la carpeta dev.

cp -R demo/* dev

Muévete a la carpeta dev.

cd dev

Actualiza tu archivo main.tf y presiona i para que input lo edite.

vim main.tf

Quita el comentario del código del cuadro rojo. Para ello, quita el # y actualiza los nombres de los buckets y las claves.

Para AWS main.tf:

El código sin comentario debería verse de la siguiente manera.

backend "s3" {
  bucket = "<tf_state_bucket_name>"
  key    = "<environment_name>.tfstate"
  region = "us-east-1"
}

Cuando se completen las actualizaciones, guárdalas y sal del editor presionando esc -> :wq!. Se guardarán las actualizaciones en main.tf.

A continuación, cambia el nombre de example.auto.tfvars a dev.auto.tfvars.

mv example.auto.tfvars dev.auto.tfvars

Actualiza dev.auto.tfvars y presiona i para que input edite el archivo.

vim dev.auto.tfvars

Actualiza los campos del cuadro rojo a continuación de la imagen con los parámetros correctos de ARN de AWS que se proporcionan durante la integración, el entorno y el correo electrónico de notificación del servicio de agregación.

Una vez que las actualizaciones estén listas, presiona esc -> :wq!. Esto guarda el archivo dev.auto.tfvars y debería verse como la siguiente imagen.

3.4. Implementa el servicio de agregación

Para implementar el servicio de agregación, inicializa Terraform en la misma carpeta /terraform/aws/environments/dev.

terraform init

Se debería mostrar un resultado similar al de la siguiente imagen:

Una vez que se inicialice Terraform, crea el plan de ejecución de Terraform. Muestra la cantidad de recursos que se agregarán y otra información adicional similar a la que se muestra en la siguiente imagen.

terraform plan

Lo puedes ver en el siguiente resumen del "Plan". Si esta es una implementación nueva, deberías ver la cantidad de recursos que se agregarán con un 0 para cambiar y 0 para destruir.

Una vez que completes este paso, podrás proceder a aplicar Terraform.

terraform apply

Cuando se te solicite confirmar para realizar las acciones de Terraform, ingresa un yes en el valor.

Una vez que finaliza terraform apply, se muestran los siguientes extremos para createJob y getJob. También se muestra el frontend_api_id que necesitas actualizar en Postman en la sección 1.9.

4. Creación de entradas del servicio de agregación

Continúa con la creación de los informes AVRO para agrupar en lotes en el servicio de agregación.

Paso 4. Creación de entradas del servicio de agregación: Crea los informes del servicio de agregación que se agrupan en lotes para el servicio de agregación.
Paso 4.1. Informe de activación
Paso 4.2: Recopila informes agregables
Paso 4.3: Convierte los informes a AVRO.
Paso 4.4. Crea el dominio de salida AVRO

4.1. Activar informe

Ve al sitio de demostración de Privacy Sandbox. Esto activa un informe de agregación privado. Puedes ver el informe en chrome://private-aggregation-internals.

Si el estado de tu informe es "Pendiente", puedes seleccionarlo y hacer clic en "Enviar informes seleccionados".

4.2. Cómo recopilar informes agregables

Recopila tus informes agregables de los extremos .well-known de tu API correspondiente.

• Agregación privada
  [reporting-origin] /.well-known/private-aggregation/report-shared-storage
• Attribution Reporting: informe de resumen
  [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

Para este codelab, realizarás la recopilación de informes de forma manual. En producción, se espera que las tecnologías publicitarias recopilen y conviertan los informes de manera programática.

En chrome://private-aggregation-internals, copia el "Cuerpo del informe" que recibiste en el extremo [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

Asegúrate de que en el "Cuerpo del informe", el aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, lo que significa que el informe es agregable de AWS.

Coloca el "cuerpo del informe" en JSON en un archivo JSON. En este ejemplo, puedes usar vim. Pero puedes usar el editor de texto que desees.

vim report.json

Pega el informe en report.json y guarda el archivo.

4.3. Convertir informes a AVRO

Los informes recibidos de los extremos .well-known están en formato JSON y se deben convertir al formato de informe AVRO. Una vez que tengas el informe JSON, navega a tu carpeta del informe y usa aggregatable_report_converter.jar para crear el informe agregable de depuración. Esto crea un informe agregable llamado report.avro en tu directorio actual.

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json

4.4. Crea el dominio de salida AVRO

Para crear el archivo output_domain.avro, necesitas las claves del bucket que se pueden recuperar a partir de los informes.

La tecnología publicitaria diseña las claves de bucket. Sin embargo, en este caso, la demostración de Privacy Sandbox del sitio crea las claves de bucket. Dado que la agregación privada de este sitio está en modo de depuración, puedes usar el debug_cleartext_payload del "Cuerpo del informe" para obtener la clave del bucket.

Copia el debug_cleartext_payload del cuerpo del informe.

Abre goo.gle/ags-payload-decoder, pega tu debug_cleartext_payload en el cuadro "INPUT" y haz clic en "INPUT".

La página muestra el valor decimal de la clave de bucket. A continuación, se muestra una clave de bucket de muestra.

Ahora que tenemos la clave del bucket, crea el output_domain.avro. Asegúrate de reemplazar por la clave del bucket que recuperaste.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

La secuencia de comandos crea el archivo output_domain.avro en tu carpeta actual.

4.5. Traslada informes al bucket de AWS

Una vez creados los informes AVRO (de la sección 3.2.3) y el dominio de salida (de la sección 3.2.4), traslada los informes y el dominio de salida a los buckets de S3 de informes.

Si tienes configurada la CLI de AWS en tu entorno local, usa los siguientes comandos para copiar los informes en el bucket de S3 y la carpeta de informes correspondientes.

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 del servicio de agregación

Desde terraform apply, se muestran create_job_endpoint, get_job_endpoint y frontend_api_id. Copia el frontend_api_id y colócalo en la variable global de postman frontend_api_id que configuraste en la sección de requisitos previos 1.9.

Paso 5: Aggregation Service Usage: Utilice la API de Aggregation Service para crear informes de resumen y revisar los informes de resumen.
Paso 5.1. Usa el extremo createJob para crear lotes
Paso 5.2: Usa el extremo getJob para recuperar el estado del lote
Paso 5.3: Revisión del informe de resumen

5.1. Usa el extremo createJob para agrupar

En Postman, abre la colección "Privacy Sandbox" y selecciona "createJob".

Selecciona "Body" y elige "raw" para colocar la carga útil de tu solicitud.

El esquema de carga útil createJob está disponible en github y es similar al siguiente. Reemplaza <> por los campos adecuados.

{
  "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"
  }
}

Una vez que haces clic en "Send", se crea el trabajo con job_request_id. Deberías recibir una respuesta HTTP 202 una vez que el servicio de agregación acepte la solicitud. Puedes encontrar otros posibles códigos de devolución en Códigos de respuesta HTTP

5.2. Usa el extremo de getJob para recuperar el estado del lote

Para verificar el estado de la solicitud de trabajo, puedes usar el extremo getJob. Selecciona “getJob” en la colección “Privacy Sandbox”.

En los “Params”, actualiza el valor de job_request_id a la job_request_id que se envió en la solicitud de createJob.

El resultado de getJob debería mostrar el estado de tu solicitud de trabajo con un estado HTTP de 200. La solicitud “Body” contiene la información necesaria, como job_status, return_message y error_messages (si se produjo un error en el trabajo).

Dado que el sitio de informes del informe de demostración generado es diferente del sitio integrado en tu ID de AWS, es posible que recibas una respuesta con el valor return_code de PRIVACY_BUDGET_AUTHORIZATION_ERROR. Esto es normal, ya que el sitio de origen de los informes de los informes no coincide con el sitio de informes integrado para el ID de 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"
    },
    "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

5.3. Revisión del informe de resumen

Una vez que recibas el informe de resumen en tu bucket de S3 de salida, podrás descargarlo en tu entorno local. Los informes de resumen están en formato AVRO y se pueden volver a convertir a JSON. Puedes usar aggregatable_report_converter.jar para leer tu informe con el siguiente comando.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>

Esto muestra un JSON de los valores agregados de cada clave de bucket que es similar a la siguiente imagen.

Si tu solicitud de createJob incluye debug_run como true, puedes recibir tu informe de resumen en la carpeta de depuración que se encuentra en output_data_blob_prefix. El informe está en formato AVRO y se puede convertir a JSON con el comando anterior.

El informe contiene la clave de bucket, la métrica sin ruido y el ruido que se agrega a la métrica sin ruido para formar el informe de resumen. El informe es similar a la siguiente imagen.

Las anotaciones también contienen in_reports y in_domain, lo que significa lo siguiente:

• in_reports: La clave de bucket está disponible dentro de los informes agregables.
• in_domain: La clave del bucket está disponible dentro del archivo AVRO de output_domain.