Informazioni sull'API Aggregation Service

Dopo il deployment, il servizio di aggregazione esporrà due endpoint per l'utilizzo della tecnologia pubblicitaria: createJob e getJob.

Diagramma AgS

Per saperne di più sugli endpoint createJob e getJob, consulta la documentazione dell'API Aggregation Service.

createJob

L'endpoint createJob viene chiamato tramite una richiesta POST HTTP e richiede un corpo della richiesta. Una volta inviata la richiesta createJob, riceverai una risposta di successo HTTP 202.

  POST https://<api-gateway>/stage/v1alpha/createJob

Un esempio del corpo della richiesta per 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>"
  }
}

Tieni presente che reporting_site e attribution_report_to sono si escludono a vicenda ed è richiesto solo uno.

Puoi anche richiedere un job di debug aggiungendo debug_run in job_parameters. Per comprendere la modalità di debug, consulta la nostra documentazione sull'esecuzione di debug dell'aggregazione.

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

Campi richiesta

Parametro Tipo Descrizione
job_request_id Stringa Si tratta di un identificatore univoco generato dalla tecnologia pubblicitaria che deve essere costituito da lettere ASCII con un massimo di 128 caratteri. Identifica la richiesta di job batch e acquisisce tutti i report avro aggregabili specificati in "input_data_blob_prefix" dal bucket di input specificato in input_data_bucket_name ospitato nello spazio di archiviazione cloud dell'ad tech.
Caratteri: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix Stringa Questo è il percorso nel bucket. Per i singoli file, puoi utilizzare il percorso. Per più file, puoi utilizzare il prefisso nel percorso.
Esempio: cartella/file raccoglierà tutti i report da cartella/file1.avro, cartella/file/file1.avro, cartella/file1/test/file2.avro.
input_data_bucket_name Stringa Si tratta del bucket di archiviazione per i dati di input o i report aggregabili. Si tratta dell'archiviazione sul cloud della tecnologia pubblicitaria.
output_data_blob_prefix Stringa Questo è il percorso di output nel bucket. È supportato un singolo file di output.
output_data_bucket_name Stringa Questo è il bucket di archiviazione a cui verrà inviato output_data. Si tratta dell'archiviazione sul cloud della tecnologia pubblicitaria.
job_parameters Dizionario Campo obbligatorio. Questa sezione conterrà i diversi campi, ad esempio:
  • 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 Stringa Analogamente a input_data_blob_prefix, questo sarà il percorso nel output_domain_bucket_name in cui si troverà AVRO del dominio di output. Per più file, puoi utilizzare il prefisso nel percorso. Una volta completato il batch, il report di riepilogo viene creato e inserito nel bucket di output output_data_bucket_name con il nome output_data_blob_prefix.
job_parameters.output_domain_bucket_name Stringa Questo è il bucket di archiviazione per il file AVRO del dominio di output. Questo riguarda lo spazio di archiviazione sul cloud della tecnologia pubblicitaria.
job_parameters.attribution_report_to Stringa Si escludono a vicenda del sito report. Si tratta dell'URL o dell'origine segnalazione da cui è stata ricevuta la segnalazione. L'origine farà parte del sito registrato nell'onboarding dei servizi di aggregazione.
job_parameters.reporting_site Stringa Si escludono a vicenda con attribution_report_to. Sarà il nome host dell'URL del report o dell'origine del report dove è stato ricevuto il report. L'origine farà parte del sito registrato nell'onboarding del servizio di aggregazione. Nota: puoi inviare report con più origini di reporting nella stessa richiesta, a condizione che tutte queste origini appartengano allo stesso sito di segnalazione menzionato in questo parametro.
job_parameters.debug_privacy_epsilon Virgola mobile, Doppio Campo facoltativo. Se non viene specificato nessuno, il valore predefinito è 10. È possibile utilizzare un valore compreso tra 0 e 64. Il valore può essere variato.
job_parameters.report_error_threshold_percentage Doppio Campo facoltativo. Si tratta della soglia della percentuale di report che può non riuscire prima che il job inizi a non riuscire. Se viene lasciato vuoto, il valore predefinito è 10%.
job_parameters.input_report_count valore lungo Campo facoltativo. Numero totale di report forniti come dati di input per questo job. Questo valore, in combinazione con report_error_threshold_percentage, consente l'interruzione anticipata del job quando i report vengono esclusi a causa di errori.
job_parameters.filtering_ids Stringa Campo facoltativo. Un elenco di ID filtro non firmati separati da virgole. Tutti i contributi, tranne l'ID filtro corrispondente, verranno filtrati. ad es. "filtering_ids": "12345,34455,12". Il valore predefinito è "0".
job_parameters.debug_run Booleano Campo facoltativo. Quando esegui una corsa di debug, vengono aggiunti report di riepilogo del debug con rumore e senza rumore e annotazioni per indicare quali chiavi sono presenti nell'input e/o nei report del dominio. Inoltre, non vengono applicati i duplicati nei vari batch. Tieni presente che l'esecuzione di debug prende in considerazione solo i report con il flag "debug_mode": "enabled" e le esecuzioni di debug consumano il budget.

getJob

Quando il team ad tech vuole conoscere lo stato di un batch richiesto, può chiamare l'endpoint getJob. L'endpoint getJob può essere chiamato utilizzando una chiamata GET HTTPS insieme al parametro job_request_id nella richiesta.

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

Dovresti ricevere una risposta simile a questa, che restituirà lo stato del job e i messaggi di errore.

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

Campi di risposta

Parametro Tipo Descrizione
job_request_id Stringa Si tratta dell'ID job/batch univoco specificato nella richiesta createJob.
job_status Stringa Questo è lo stato della richiesta di job.
request_received_at Stringa L'ora in cui la richiesta è stata ricevuta.
request_updated_at Stringa L'ora dell'ultimo aggiornamento del job.
input_data_blob_prefix Stringa Si tratta del prefisso dei dati di input impostato su createJob.
input_data_bucket_name Stringa Si tratta del bucket di dati di input dell'ad tech in cui vengono archiviati i report aggregabili. Questo campo è impostato su createJob.
output_data_blob_prefix Stringa Si tratta del prefisso dei dati di output impostato su createJob.
output_data_bucket_name Stringa Il bucket di dati di output della tecnologia pubblicitaria in cui verranno archiviati i report di riepilogo una volta generati. Questo campo è impostato su createJob.
request_processing_started_at Stringa L'ora in cui è iniziato l'ultimo tentativo di elaborazione. In questo modo verrà escluso il tempo di attesa nella coda dei job. (Tempo di elaborazione totale = request_updated_at - request_processing_started_at)
result_info Dizionario Questo è il risultato dell'createJob e di tutte le informazioni disponibili sul job. Verranno visualizzati return_code, return_message, finished_at e error_summary.
result_info.return_code Stringa Il codice di ritorno del risultato del job. Queste informazioni saranno necessarie quando si verifica un problema nel servizio di aggregazione per capire quale potrebbe essere il problema.
result_info.return_message Stringa Il messaggio (riuscita o non riuscita) che viene restituito in seguito al job. Queste informazioni saranno necessarie anche durante l'indagine degli errori del servizio di aggregazione.
result_info.error_summary Dizionario Gli errori restituiti per il job. Verrà indicato il numero di report non riusciti e il tipo di errore.
result_info.finished_at Timestamp Il timestamp del completamento del job.
result_info.error_summary.error_counts Elenco Verrà restituito un elenco dei messaggi di errore e il numero di segnalazioni non riuscite con lo stesso messaggio di errore. Ogni conteggio degli errori conterrà la categoria, error_count, description.
result_info.error_summary.error_messages Elenco Verrà restituito un elenco dei messaggi di errore dei report che non è stato possibile elaborare.
job_parameters Dizionario Contiene i parametri del job forniti nella richiesta createJob. Proprietà pertinenti come "output_domain_blob_prefix" e "output_domain_bucket_name".
job_parameters.attribution_report_to Stringa Simultanea in esclusiva per reporting_site. Si tratta dell'URL o dell'origine del report in cui è stato ricevuto il report. L'origine farà parte del sito registrato nell'onboarding del servizio di aggregazione. Questo valore è specificato nella richiesta createJob.
job_parameters.reporting_site Stringa Si escludono a vicenda con attribution_report_to. Si tratta del nome host dell'URL del report o dell'origine report in cui è stato ricevuto il report. L'origine farà parte del sito registrato nell'onboarding del servizio di aggregazione. Tieni presente che puoi inviare report con più origini report nella stessa richiesta, a condizione che tutte le origini report appartengano allo stesso sito di generazione di report indicato in questo parametro. Questo valore è specificato nella richiesta createJob. Inoltre, assicurati che il bucket contenga solo i report da aggregati al momento della creazione del job. Verranno elaborati tutti i report aggiunti al bucket di dati di input con origini report corrispondenti al sito di report specificato nel parametro del job. Ad esempio, se un'ad tech ha registrato un'origine report https://exampleabc.com, ma all'interno del bucket di dati di input viene aggiunta ai report di https://1.exampleabc.com, https://2.exampleabc.com e https://3.examplexyz.com. Verranno aggregati solo i report aggiunti nel bucket che corrispondono all'origine report registrata nel job, ovvero https://exampleabc.com.
job_parameters.debug_privacy_epsilon Virgola mobile, doppio Campo facoltativo. Se non viene specificato nessuno, il valore predefinito è 10. È possibile utilizzare un valore compreso tra 0 e 64. Il valore può variare. Questo valore è specificato nella richiesta createJob.
job_parameters.report_error_threshold_percentage Doppio Campo facoltativo. Si tratta della soglia della percentuale di report che può non riuscire prima che il job inizi a non riuscire. Se viene lasciato vuoto, il valore predefinito è 10%. Questo valore è specificato nella richiesta createJob.
job_parameters.input_report_count Valore lungo Campo facoltativo. Numero totale di report forniti come dati di input per questo job. Questo valore, in combinazione con report_error_threshold_percentage, consente l'interruzione anticipata del job quando i report vengono esclusi a causa di errori. Questo valore è specificato nella richiesta createJob.
job_parameters.filtering_ids Stringa Campo facoltativo. Un elenco di ID filtro non firmati separati da virgole. Tutti i contributi diversi dall'ID filtro corrispondente verranno filtrati. Questo valore è specificato nella richiesta createJob. (ad es. "filtering_ids":"12345,34455,12". Il valore predefinito è "0".