Comprendre l'API Service Aggregation

Après le déploiement, le service d'agrégation expose deux points de terminaison pour l'utilisation de la technologie publicitaire: createJob et getJob.

Diagramme AgS

Pour en savoir plus sur les points de terminaison createJob et getJob, consultez la documentation de l'API du service d'agrégation.

createJob

Le point de terminaison createJob est appelé via une requête HTTP POST et nécessite un corps de requête. Une fois la requête createJob envoyée, vous recevrez une réponse HTTP 202 indiquant que la requête a bien été prise en compte.

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

Notez que reporting_site et attribution_report_to sont mutuellement exclusifs, et qu'un seul de ces éléments est requis.

Vous pouvez également demander une tâche de débogage en ajoutant debug_run dans job_parameters. Pour comprendre le mode débogage, consultez notre documentation sur l'exécution du débogage de l'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 de requête

Paramètre Type Description
job_request_id Chaîne Il s'agit d'un identifiant unique généré par une technologie publicitaire. Il doit être composé de lettres ASCII ne dépassant pas 128 caractères. Cela identifie la requête de job par lot et prendra 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é sur le 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 dans le bucket. Pour des fichiers individuels, vous pouvez utiliser le chemin d'accès. Pour plusieurs fichiers, vous pouvez utiliser le préfixe du chemin d'accès.
Exemple : folder/file 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 pour les données d'entrée ou les rapports agrégables. C'est dans le 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 pris en charge.
output_data_bucket_name Chaîne Il s'agit du bucket de stockage dans lequel l'output_data sera envoyé. Il s'agit du stockage cloud de la technologie publicitaire.
job_parameters Dictionnaire Champ obligatoire. Il 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 situe l'AVRO de votre domaine de sortie. 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 S'exclut mutuellement avec reporting_site. Il s'agit de l'URL ou de l'origine du rapport où le rapport a été reçu. L'origine fait partie du site enregistré 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 fera partie du site enregistré dans l'intégration du service d'agrégation. Remarque : Vous pouvez envoyer des rapports avec plusieurs origines de rapports dans la même requête, à condition que toutes les origines de rapports appartiennent au même site de rapports mentionné dans ce paramètre.
job_parameters.debug_privacy_epsilon Valeur à 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. La valeur peut être différente.
job_parameters.report_error_threshold_percentage Double Champ facultatif. Il s'agit du seuil du pourcentage de rapports pouvant échouer avant que la tâche ne commence à échouer. Si vous ne renseignez pas ce champ, 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 cette tâche. Cette valeur, associée à report_error_threshold_percentage, permet d'arrêter prématurément la tâche 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 seront filtrées. 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", et qu'elle consomme le budget.

getJob

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

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

Vous devriez obtenir une réponse semblable à celle-ci, qui indiquera l'état du job ainsi que des 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 job / de 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 de réception de la demande.
request_updated_at Chaîne Heure de la dernière mise à jour du job.
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 seront stockés une fois généré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. (Temps de traitement total = request_updated_at - request_processing_started_at)
result_info Dictionnaire Il s'agit du résultat de createJob et de toutes les informations disponibles sur la tâche. Les attributs return_code, return_message, finished_at et error_summary s'affichent.
result_info.return_code Chaîne Code renvoyé du résultat de la tâche. Ces informations seront nécessaires en cas de problème dans le service d'agrégation pour identifier la cause du problème.
result_info.return_message Chaîne Message (succès ou échec) renvoyé en tant que résultat de la tâche. Ces informations seront également nécessaires lors de l'investigation des défaillances du service d'agrégation.
result_info.error_summary Dictionnaire Les erreurs renvoyées pour la tâche. Il indique le nombre de rapports qui ont échoué et le type d'erreur.
result_info.finished_at Horodatage Code temporel de la fin de la tâche.
result_info.error_summary.error_counts Liste Une liste des messages d'erreur et du nombre de rapports ayant échoué avec le même message d'erreur s'affiche. Chaque nombre d'erreurs contient une catégorie, error_count, description.
result_info.error_summary.error_messages Liste Une liste des messages d'erreur des rapports qui n'ont pas pu être traités s'affiche.
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 ou de l'origine du rapport où le rapport a été reçu. L'origine fera 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 Exclusivité mutuelle de 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 fait partie du site enregistré lors de l'intégration du service d'agrégation. Notez que vous pouvez envoyer des signalements avec plusieurs origines dans la même demande, à condition que toutes les origines appartiennent au même site de signalement mentionné dans ce paramètre. Cette information est spécifiée dans la requête createJob. En outre, assurez-vous que le bucket ne contient que les rapports que vous souhaitez agréger au moment de la création du job. Tous les rapports ajoutés à ce bucket de données d'entrée dont les origines de création correspondent au site de création de rapports spécifié dans le paramètre de tâche seront traités. Par exemple, si une technologie publicitaire a enregistré une origine de création de rapports https://exampleabc.com, mais qu'elle l'ajoute dans le bucket de données d'entrée, elle ajoute les rapports de https://1.exampleabc.com, https://2.exampleabc.com et https://3.examplexyz.com. Seuls les rapports ajoutés au bucket correspondant à l'origine de création de rapports enregistrée dans la tâche (https://exampleabc.com) seront agrégés.
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. La valeur peut varier. Cette information est spécifiée dans la requête createJob.
job_parameters.report_error_threshold_percentage Double Champ facultatif. Il s'agit du seuil du pourcentage de rapports pouvant échouer avant que le job ne commence à échouer. Si vous ne renseignez pas ce champ, la valeur par défaut est 10 %. 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. Cette valeur, associée à report_error_threshold_percentage, permet l'échec anticipé de la tâche lorsque les rapports sont exclus en raison d'erreurs. Cette information est spécifiée 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 seront filtrées. Cela est spécifié dans la requête createJob. (par exemple, "filtering_ids":"12345,34455,12") La valeur par défaut est "0".)