1. Requisitos previos
Para realizar este codelab, se requieren algunos requisitos previos. Cada requisito se marca según corresponda según sea necesario para las "Pruebas locales" o el "Servicio de agregación".
1.1. Descargar la herramienta de prueba local (prueba local)
Debes descargar la herramienta para realizar 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 Lambda en GitHub. Debe llamarse 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 comprobar si tu máquina tiene Java o openJDK instalados.
Si no está instalado, puedes descargarlo e instalarlo desde el sitio de Java o el sitio de openJDK.
1.3. Descargar el convertidor de informes agregables (servicio de pruebas y agregación locales)
Puedes descargar una copia del convertidor de informes agregables desde el repositorio de GitHub de demostraciones de Privacy Sandbox.
1.4. Habilita las APIs de Privacy Sandbox (servicio de pruebas y agregación locales)
En tu navegador, ve a chrome://flags/#privacy-sandbox-ads-apis y habilita las APIs de Privacy Sandbox.
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 el modo Incógnito".
1.5. Inscripción web y en 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 certificación para Chrome y Android.
Para las pruebas locales, la inscripción se puede inhabilitar mediante una marca de Chrome y un interruptor de 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 usarás nuestro sitio de demostración, no es necesario que realices ninguna actualización.
1.6. Integración del servicio de agregación (servicio de agregación)
El servicio de agregación requiere la incorporación de los coordinadores para poder usar el servicio. Completa el formulario de integración de servicios de agregación. Para ello, proporciona la dirección del 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 usa un entorno de nube. El servicio de agregación es compatible con Amazon Web Services (AWS) y Google Cloud (GCP). En este codelab, solo se abarcará la integración de AWS.
AWS proporciona un entorno de ejecución confiable llamado enclaves de Nitro. 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 con las instrucciones de configuración de CLI.
1.7.1. Crea un bucket S3 de AWS
Crea un bucket de S3 de AWS para almacenar el estado de Terraform y otro bucket de S3 para almacenar tus informes de resumen. Puedes usar el comando de CLI proporcionado. Reemplaza el campo en <> por las variables correspondientes.
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 de usuario con la guía de AWS. Se usará para llamar a los extremos de las APIs createJob y getJob creados en AWS.
1.7.3. Permisos de usuario y grupo de AWS
Para implementar el servicio de agregación en AWS, deberás otorgar ciertos permisos al usuario que se usa para implementar el servicio. Para este codelab, asegúrate de que el usuario tenga acceso de administrador a fin de tener todos los permisos 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 del servicio de agregación)
En este codelab, usa Postman para administrar solicitudes.
Para crear un lugar de trabajo, ve al elemento de navegación superior “Lugares de trabajo” y selecciona “Crear lugar de trabajo”.
Selecciona "Espacio de trabajo en blanco", haz clic en Siguiente y asígnale el nombre "Privacy Sandbox". Selecciona "Personal" y haz clic en "Crear".
Descarga los archivos de configuración JSON y de entorno global del lugar de trabajo preconfigurados.
Importa los archivos JSON a “Mi lugar de trabajo” con el botón “Importar”.
Esto creará la colección de Privacy Sandbox para ti junto con las solicitudes HTTP createJob y getJob.
Actualiza la “Clave de acceso” y la “Clave secreta” de AWS a través de “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 quieres realizar la implementación en una región diferente, asegúrate de copiar la AMI actualizada en tu cuenta o realizar una autocompilación con las secuencias de comandos proporcionadas.
2. Codelab de pruebas locales
Puedes usar la herramienta de prueba local en tu máquina para realizar agregaciones y generar informes de resumen mediante 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: Crea un informe agregable de depuración: Convierte el informe JSON recopilado en un informe con formato AVRO.
Este paso será similar a cuando las plataformas de tecnología publicitaria recopilan los informes de los extremos de informes de la API y convierten los informes JSON en informes con formato AVRO.
Paso 2.3: Analizar la clave de bucket del informe de depuración: Las tecnologías publicitarias diseñan las claves de bucket. En este codelab, dado que los buckets están predefinidos, recupera las claves de bucket según se proporcionen.
Paso 2.4: Crea el dominio de salida AVRO: una vez que se recuperen las claves de bucket, crea el archivo AVRO del dominio de salida.
Paso 2.5: Crea informes de resumen con la herramienta de pruebas locales: Usa esta herramienta para poder crear informes de resumen en el entorno local.
Paso 2.6: Revisa 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 tu informe se encuentra en el estado "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", aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, lo que significa que el informe es un informe agregable de AWS.
Coloca el JSON "Report Body" 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 tu archivo.
Una vez que lo tengas, 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 de bucket desde el informe de depuración
El servicio de agregación requiere dos archivos para el procesamiento por 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 de bucket que se pueden recuperar de los informes.
El llamador de la API diseña las claves de bucket, y la demostración contiene claves de bucket de ejemplo preconstruidas. Dado que la demostración habilitó el modo de depuración para Private Aggregation, puedes analizar la carga útil de depuración de texto simple desde el "Cuerpo del informe" para recuperar la clave 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 se encuentra en modo de depuración, puedes usar debug_cleartext_payload del "Cuerpo del informe" para obtener la clave de bucket.
Copia el debug_cleartext_payload del cuerpo del informe.
Abre el decodificador de carga útil de depuración para la herramienta de 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. La siguiente es 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 esta. Continúa con la creación del output_domain.avro con la clave del bucket. Asegúrate de reemplazar
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
La secuencia de comandos crea el archivo output_domain.avro en la carpeta actual.
2.5. Crear informes de resumen con la herramienta de pruebas local
Usaremos un archivo 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. Una vez que se complete, se creará un informe output.avro.
2.6 Cómo revisar el informe de resumen
El informe de resumen que se crea está en formato AVRO. Para poder leer esto, debes convertirlo de AVRO a un formato JSON. Idealmente, la tecnología publicitaria debería codificar para volver a convertir los informes de AVRO a JSON.
En nuestro codelab, usaremos la herramienta aggregatable_report_converter.jar proporcionada para volver a convertir el informe de AVRO a 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. Descarga dependencias compiladas previamente
Una vez que hayas clonado el repositorio del servicio de agregación, ve a la carpeta Terraform del repositorio y a la carpeta de la nube correspondiente. Si tu cloud_provider es AWS, puedes ir a
cd <repository_root>/terraform/aws
En download_prebuilt_dependencies.sh.
bash download_prebuilt_dependencies.sh
3.3. Crea un entorno de desarrollo
Crea un entorno de desarrollo en dev.
mkdir dev
Copia el contenido de la carpeta demo en la carpeta dev.
cp -R demo/* dev
Muévete a tu carpeta dev.
cd dev
Actualiza el 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 del bucket y las claves.
Para el archivo main.tf de AWS:
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 cierra el editor presionando esc -> :wq!. Guarda 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 con los parámetros de ARN de AWS correctos que se proporcionan durante el correo electrónico de notificación, entorno y incorporación del servicio de agregación.
Cuando finalices las actualizaciones, presiona esc -> :wq!. Se guardará 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, en la misma carpeta
terraform init
Se debería mostrar un resultado similar al de la siguiente imagen:
Una vez que se inicialice Terraform, crea su plan de ejecución. Donde muestra la cantidad de recursos que se agregarán y otra información adicional similar a la de la siguiente imagen.
terraform plan
Puedes ver en el siguiente resumen "Plan". Si se trata de una implementación nueva, deberías ver la cantidad de recursos que se agregarán, con 0 para cambiar y 0 para destruir.
Cuando termines, puedes proceder a aplicar Terraform.
terraform apply
Cuando Terraform te solicite confirmar que quieres realizar las acciones, ingresa un yes en el valor.
Una vez que finaliza terraform apply, se devuelven los siguientes extremos para createJob y getJob. También se muestra el frontend_api_id que debes actualizar en Postman en la sección 1.9.
4. Creación de entradas del servicio de agregación
Continuar 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 del activador
Paso 4.2: Recopila informes agregables
Paso 4.3. Convierte los informes al formato 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 tu informe se encuentra en el estado "Pendiente", puedes seleccionarlo y hacer clic en "Enviar informes seleccionados".
4.2. Recopila 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 - Informes de atribución: informe de resumen
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
En este codelab, realizarás la recopilación de informes de forma manual. En producción, se espera que las plataformas de tecnología publicitaria 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", aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, lo que significa que el informe es un informe agregable de AWS.
Coloca el JSON "Report Body" 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 tu archivo.
4.3. Convierte informes a AVRO
Los informes recibidos de los extremos .well-known están en formato JSON y deben convertirse al formato de informe AVRO. Una vez que tengas el informe JSON, navega a tu carpeta de informes y utiliza aggregatable_report_converter.jar para ayudar a 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 de bucket que se pueden recuperar de los informes.
La tecnología publicitaria diseña las claves de bucket. Sin embargo, en este caso, el sitio demostración de Privacy Sandbox crea las claves de bucket. Dado que la agregación privada de este sitio se encuentra en modo de depuración, puedes usar debug_cleartext_payload del "Cuerpo del informe" para obtener la clave de 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. La siguiente es una clave de bucket de muestra.
Ahora que tenemos la clave del bucket, crea el output_domain.avro. Asegúrate de reemplazar
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
La secuencia de comandos crea el archivo output_domain.avro en la carpeta actual.
4.5. Mueve los informes al bucket de AWS
Una vez que se hayan creado los informes de AVRO (de la sección 3.2.3) y el dominio de salida (de la sección 3.2.4), mueve los informes y el dominio de salida a los buckets de informes de S3.
Si tienes la CLI de AWS configurada 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: Usa la API de Aggregation Service para crear informes de resumen y revisar los informes de resumen.
Paso 5.1. Usa createJob Endpoint para distribuir por lotes
Paso 5.2. Cómo usar getJob Endpoint para recuperar el estado del lote
Paso 5.3. Revisión del informe de resumen
5.1. Usa el extremo createJob para agrupar en lotes
En Postman, abre la colección “Privacy Sandbox” y selecciona “createJob”.
Selecciona "Cuerpo" y "sin procesar" 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 hagas clic en “Enviar”, se creará el trabajo con job_request_id. Una vez que el servicio de agregación acepte la solicitud, deberías recibir una respuesta HTTP 202. Puedes encontrar otros posibles códigos de devolución en los códigos de respuesta HTTP.
5.2. Usa getJob Endpoint 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 al job_request_id que se envió en la solicitud 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 el trabajo tiene errores).
Como 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 del 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-news.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 el bucket de S3 de salida, puedes 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 el informe con el siguiente comando.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
Esto muestra un JSON de 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 el 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 un archivo JSON usando 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 al de la siguiente imagen.
Las anotaciones también contienen in_reports y in_domain, que significan lo siguiente:
- in_reports: La clave de bucket está disponible dentro de los informes agregables.
- in_domain: La clave de bucket está disponible en el archivo AVRO de output_domain.