Cette page a été traduite par l'API Cloud Translation.

Déployer et gérer des requêtes avec le service d'agrégation

Une fois le service d'agrégation déployé, vous pouvez utiliser les points de terminaison createJob et getJob pour interagir avec le service. Le diagramme suivant fournit une représentation visuelle de l'architecture de déploiement de ces deux points de terminaison:

Présentation de l'API Service Aggregation — **Figure 1.**Présentation de l'API du service d'agrégation

Pour en savoir plus sur les points de terminaison createJob et getJob, consultez la documentation de l'API Aggregation Service.

Créer une tâche

Pour créer un job, envoyez une requête POST au point de terminaison createJob. bash POST https://<api-gateway>/stage/v1alpha/createJob -+ Exemple de corps de requête pour createJob:

{
  "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>",
    "reporting_site": "<host name of reporting origin>"
  }
}

Si la tâche a bien été créée, le code d'état HTTP 202 s'affiche.

Notez que reporting_site et attribution_report_to s'excluent mutuellement et qu'un seul est obligatoire.

Vous pouvez également demander un travail de débogage en ajoutant debug_run dans job_parameters. Pour en savoir plus sur le mode débogage, consultez la documentation sur l'exécution de débogage d'agrégation.

{
  "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>"
    "debug_run": "true"
  }
}

Champs des demandes

Paramètre	Type	Description
`job_request_id`	Chaîne	Il s'agit d'un identifiant unique généré par la technologie publicitaire. Il doit être composé de lettres ASCII et ne pas comporter plus de 128 caractères. Cela identifie la requête de tâche par lot et récupère tous les rapports AVRO agrégables spécifiés dans "input_data_blob_prefix" à partir du bucket d'entrée spécifié dans "input_data_bucket_name", qui est hébergé dans l'espace de stockage cloud de la technologie publicitaire. Caractères: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
`input_data_blob_prefix`	Chaîne	Il s'agit du chemin d'accès au bucket. Pour les fichiers individuels, vous pouvez utiliser le chemin d'accès. Pour plusieurs fichiers, vous pouvez utiliser le préfixe dans le chemin d'accès. Exemple: Le dossier/fichier collecte tous les rapports de folder/file1.avro, folder/file/file1.avro et folder/file1/test/file2.avro.
`input_data_bucket_name`	Chaîne	Il s'agit du bucket de stockage des données d'entrée ou des rapports agrégables. Il s'agit du stockage cloud de la technologie publicitaire.
`output_data_blob_prefix`	Chaîne	Il s'agit du chemin d'accès de sortie dans le bucket. Un seul fichier de sortie est accepté.
`output_data_bucket_name`	Chaîne	Il s'agit du bucket de stockage dans lequel l'`output_data` est envoyé. Il se trouve dans l'espace de stockage cloud de la technologie publicitaire.
`job_parameters`	Dictionnaire	Champ obligatoire. Ce champ contient les différents champs, par exemple : `output_domain_blob_prefix` `output_domain_bucket_name` `attribution_report_to` `reporting_site` `debug_privacy_epsilon` `report_error_threshold_percentage`
`job_parameters.output_domain_blob_prefix`	Chaîne	Comme pour `input_data_blob_prefix`, il s'agit du chemin d'accès dans `output_domain_bucket_name` où se trouve votre domaine de sortie AVRO. Pour plusieurs fichiers, vous pouvez utiliser le préfixe dans le chemin d'accès. Une fois que le service d'agrégation a terminé le lot, le rapport récapitulatif est créé et placé dans le bucket de sortie `output_data_bucket_name` avec le nom `output_data_blob_prefix`.
`job_parameters.output_domain_bucket_name`	Chaîne	Il s'agit du bucket de stockage de votre fichier AVRO de domaine de sortie. Il s'agit du stockage cloud de la technologie publicitaire.
`job_parameters.attribution_report_to`	Chaîne	Cette valeur est mutuellement exclusive de "reporting_site". Il s'agit de l'URL ou de l'origine du rapport où le rapport a été reçu. L'origine du site est enregistrée lors de l'intégration du service d'agrégation.
`job_parameters.reporting_site`	Chaîne	S'exclut mutuellement avec `attribution_report_to`. Il s'agit du nom d'hôte de l'URL de création de rapports ou de l'origine de création de rapports où le rapport a été reçu. L'origine du site est enregistrée lors de l'intégration du service d'agrégation. Remarque: Vous pouvez envoyer plusieurs rapports avec des origines différentes dans une même requête, à condition que toutes les origines appartiennent au même site de création de rapports spécifié dans ce paramètre.
`job_parameters.debug_privacy_epsilon`	Virgule flottante, double	Champ facultatif. Si aucune valeur n'est transmise, la valeur par défaut est 10. Vous pouvez utiliser une valeur comprise entre 0 et 64.
`job_parameters.report_error_threshold_percentage`	Double	Champ facultatif. Il s'agit du pourcentage maximal de rapports ayant échoué autorisé avant l'échec de la tâche. Si vous ne spécifiez pas de valeur, la valeur par défaut est 10%.
`job_parameters.input_report_count`	valeur longue	Champ facultatif. Nombre total de rapports fournis en tant que données d'entrée pour la tâche. Cette valeur, associée à `report_error_threshold_percentage`, permet d'arrêter la tâche plus tôt lorsque des rapports sont exclus en raison d'erreurs.
`job_parameters.filtering_ids`	Chaîne	Champ facultatif. Liste d'ID de filtrage non signés séparés par une virgule. Toutes les contributions autres que l'ID de filtrage correspondant sont filtrées. (par exemple, `"filtering_ids": "12345,34455,12"`). La valeur par défaut est 0.
`job_parameters.debug_run`	Booléen	Champ facultatif. Lorsque vous exécutez une analyse de débogage, des rapports et des annotations de débogage avec et sans bruit sont ajoutés pour indiquer quelles clés sont présentes dans l'entrée de domaine et/ou les rapports. De plus, les doublons entre les lots ne sont pas non plus appliqués. Notez que l'exécution de débogage ne prend en compte que les rapports associés à l'indicateur `"debug_mode": "enabled"`. Depuis la version 2.10.0, les exécutions de débogage ne consomment pas de budget de confidentialité.

Obtenir une tâche

Lorsqu'une technologie publicitaire souhaite connaître l'état d'un lot demandé, elle peut appeler le point de terminaison getJob. Le point de terminaison getJob est appelé à l'aide d'une requête GET HTTPS avec le paramètre job_request_id.

  GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>

Vous devriez obtenir une réponse qui renvoie l'état de la tâche, ainsi que d'éventuels messages d'erreur:

{
    "job_status": "FINISHED",
    "request_received_at": "2023-07-17T19:15:13.926530Z",
    "request_updated_at": "2023-07-17T19:15:28.614942839Z",
    "job_request_id": "PSD_0003",
    "input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
    "input_data_bucket_name": "ags-report-bucket",
    "output_data_blob_prefix": "summary/summary.avro",
    "output_data_bucket_name": "ags-report-bucket",
    "postback_URL": "",
    "result_info": {
        "return_code": "SUCCESS",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-07-17T19:15:28.607802354Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "ags-report-bucket",
        "output_domain_blob_prefix": "output_domain/output_domain.avro",
        "attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
    },
    "request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}

Champs de réponse

Paramètre	Type	Description
`job_request_id`	Chaîne	Il s'agit de l'ID de tâche/lot unique spécifié dans la requête `createJob`.
`job_status`	Chaîne	Il s'agit de l'état de la requête de tâche.
`request_received_at`	Chaîne	Heure à laquelle la requête a été reçue.
`request_updated_at`	Chaîne	Heure de la dernière mise à jour de la tâche.
`input_data_blob_prefix`	Chaîne	Il s'agit du préfixe des données d'entrée défini sur `createJob`.
`input_data_bucket_name`	Chaîne	Il s'agit du bucket de données d'entrée de la technologie publicitaire dans lequel les rapports agrégables sont stockés. Ce champ est défini sur `createJob`.
`output_data_blob_prefix`	Chaîne	Il s'agit du préfixe de données de sortie défini sur `createJob`.
`output_data_bucket_name`	Chaîne	Il s'agit du bucket de données de sortie de la technologie publicitaire dans lequel les rapports récapitulatifs générés sont stockés. Ce champ est défini sur `createJob`.
`request_processing_started_at`	Chaîne	Heure de début de la dernière tentative de traitement. Cela exclut le temps d'attente dans la file d'attente des tâches. (Durée de traitement totale = `request_updated_at` - `request_processing_started_at`)
`result_info`	Dictionnaire	Il s'agit du résultat de la requête `createJob` et comprend toutes les informations disponibles. Les valeurs `return_code`, `return_message`, `finished_at` et `error_summary` s'affichent.
`result_info.return_code`	Chaîne	Code de retour du résultat de la tâche. Ces informations sont nécessaires pour résoudre les problèmes liés au service d'agrégation.
`result_info.return_message`	Chaîne	Message de réussite ou d'échec renvoyé à la suite de la tâche. Ces informations sont également nécessaires pour résoudre les problèmes liés au service d'agrégation.
`result_info.error_summary`	Dictionnaire	Les erreurs renvoyées par la tâche. Il contient le nombre de rapports ainsi que le type d'erreurs rencontrées.
`result_info.finished_at`	Horodatage	Code temporel indiquant la fin de la tâche.
`result_info.error_summary.error_counts`	Liste	Cette commande renvoie une liste des messages d'erreur, ainsi que le nombre de rapports ayant échoué avec le même message d'erreur. Chaque compte d'erreur contient une catégorie, `error_count` et `description`.
`result_info.error_summary.error_messages`	Liste	Cette commande renvoie la liste des messages d'erreur des rapports dont le traitement a échoué.
`job_parameters`	Dictionnaire	Il contient les paramètres de tâche fournis dans la requête `createJob`. Propriétés pertinentes telles que "output_domain_blob_prefix" et "output_domain_bucket_name".
`job_parameters.attribution_report_to`	Chaîne	S'exclut mutuellement avec `reporting_site`. Il s'agit de l'URL de création du rapport ou de l'origine du rapport. L'origine fait partie du site enregistré dans l'intégration du service d'agrégation. Cette information est spécifiée dans la requête `createJob`.
`job_parameters.reporting_site`	Chaîne	S'exclut mutuellement avec `attribution_report_to`. Il s'agit du nom d'hôte de l'URL de création de rapports ou de l'origine du rapport. L'origine fait partie du site enregistré dans l'intégration du service d'agrégation. Notez que vous pouvez envoyer des rapports avec plusieurs origines de création de rapports dans la même requête, à condition que toutes les origines de création de rapports appartiennent au même site mentionné dans ce paramètre. Cette information est spécifiée dans la requête `createJob`. Assurez-vous également que le bucket ne contient que les rapports que vous souhaitez agréger au moment de la création de la tâche. Tous les rapports ajoutés au bucket de données d'entrée dont les origines correspondent au site de création de rapports spécifié dans le paramètre de tâche sont traités. Le service d'agrégation ne prend en compte que les rapports du bucket de données qui correspondent à l'origine de création des rapports enregistrée pour la tâche. Par exemple, si l'origine enregistrée est https://exampleabc.com, seuls les rapports provenant de https://exampleabc.com sont inclus, même si le bucket contient des rapports provenant de sous-domaines (`https://1.exampleabc.com`, etc.) ou de domaines entièrement différents (`https://3.examplexyz.com`).
`job_parameters.debug_privacy_epsilon`	Virgule flottante, double	Champ facultatif. Si aucune valeur n'est transmise, la valeur par défaut de 10 est utilisée. Les valeurs peuvent être comprises entre 0 et 64. Cette valeur est spécifiée dans la requête `createJob`.
`job_parameters.report_error_threshold_percentage`	Double	Champ facultatif. Il s'agit du pourcentage de seuil de rapports pouvant échouer avant l'échec de la tâche. Si aucune valeur n'est attribuée, la valeur par défaut de 10% est utilisée. Cette information est spécifiée dans la requête `createJob`.
`job_parameters.input_report_count`	Valeur longue	Champ facultatif. Nombre total de rapports fournis en tant que données d'entrée pour cette tâche. Combiné à cette valeur, le paramètre "report_error_threshold_percentage" déclenche l'échec prématuré de la tâche si un nombre important de rapports sont exclus en raison d'erreurs. Ce paramètre est spécifié dans la requête "createJob".
`job_parameters.filtering_ids`	Chaîne	Champ facultatif. Liste d'ID de filtrage non signés séparés par une virgule. Toutes les contributions autres que l'ID de filtrage correspondant sont filtrées. Cette information est spécifiée dans la requête `createJob`. (par exemple, `"filtering_ids":"12345,34455,12"`) La valeur par défaut est "0".)