Questa pagina è stata tradotta dall'API Cloud Translation.

Esegui il deployment e gestisci le richieste con il servizio di aggregazione

Dopo aver eseguito il deployment del servizio di aggregazione, puoi utilizzare gli endpoint createJob e getJob per interagire con il servizio. Il seguente diagramma fornisce una rappresentazione visiva dell'architettura di deployment per questi due endpoint:

Panoramica dell'API Aggregation Service — **Figura 1.**Panoramica dell'API del servizio di aggregazione

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

Crea un job

Per creare un job, invia una richiesta POST all'endpoint createJob. bash 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>"
  }
}

La creazione di un job riuscita genera un codice di stato HTTP 202.

Tieni presente che reporting_site e attribution_report_to sono esclusivi l'uno dell'altro e ne è richiesto solo uno.

Puoi anche richiedere un job di debug aggiungendo debug_run in job_parameters. Per ulteriori informazioni sulla modalità di debug, consulta la nostra documentazione relativa all'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 di 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. Questo identifica la richiesta di job batch e recupera tutti i report AVRO aggregabili specificati in "input_data_blob_prefix" dal bucket di input specificato in "input_data_bucket_name" che è ospitato nello spazio di archiviazione cloud dell'ad tech. Caratteri: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
`input_data_blob_prefix`	Stringa	Questo è il percorso del bucket. Per i singoli file, puoi utilizzare il percorso. Per più file, puoi utilizzare il prefisso nel percorso. Esempio: la cartella/il file raccoglie tutti i report da cartella/file1.avro, cartella/file/file1.avro e 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 solo file di output.
`output_data_bucket_name`	Stringa	Questo è il bucket di archiviazione in cui viene inviato `output_data`. Questo file esiste nello spazio di archiviazione sul cloud dell'ad tech.
`job_parameters`	Dizionario	Campo obbligatorio. Questo campo contiene 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`, si tratta del percorso in `output_domain_bucket_name` in cui si trova il dominio AVRO 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. Si tratta dell'archiviazione sul cloud della tecnologia pubblicitaria.
`job_parameters.attribution_report_to`	Stringa	Questo valore è mutuamente esclusivo di "reporting_site". Si tratta dell'URL o dell'origine del report in cui è stato ricevuto il report. L'origine del sito è registrata nell'onboarding del servizio di aggregazione.
`job_parameters.reporting_site`	Stringa	Si escludono a vicenda con `attribution_report_to`. Si tratta del nome host dell'URL o dell'origine report in cui è stato ricevuto il report. L'origine del sito è registrata nell'onboarding del servizio di aggregazione. Nota: puoi inviare più report con origini diverse in un'unica richiesta, a condizione che tutte le origini appartengano allo stesso sito di generazione di report specificato in questo parametro.
`job_parameters.debug_privacy_epsilon`	Virgola mobile, Doppio	Campo facoltativo. Se non viene passato alcun valore, il valore predefinito è 10. È possibile utilizzare un valore compreso tra 0 e 64.
`job_parameters.report_error_threshold_percentage`	Doppio	Campo facoltativo. Si tratta della percentuale massima di report non riusciti consentita prima che il job non vada a buon fine. Se non viene specificato, il valore predefinito è 10%.
`job_parameters.input_report_count`	valore lungo	Campo facoltativo. Il numero totale di report forniti come dati di input per il 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 una virgola. Tutti i contributi diversi dall'ID filtro corrispondente vengono 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, i duplicati tra i batch non vengono applicati. Tieni presente che l'esecuzione di debug prende in considerazione solo i report con il flag `"debug_mode": "enabled"`. A partire dalla versione 2.10.0, le esecuzioni di debug non consumano il budget per la privacy.

Recupero di un job

Quando un fornitore di tecnologia pubblicitaria vuole conoscere lo stato di un batch richiesto, può chiamare l'endpoint getJob. L'endpoint getJob viene chiamato utilizzando una richiesta GET HTTPS insieme al parametro job_request_id.

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

Dovresti ricevere una risposta che restituisce lo stato del job insieme a eventuali 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 è stata ricevuta la richiesta.
`request_updated_at`	Stringa	L'ora dell'ultimo aggiornamento del job.
`input_data_blob_prefix`	Stringa	Questo è il 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 sono archiviati i report aggregabili. Questo campo è impostato su `createJob`.
`output_data_blob_prefix`	Stringa	Questo è il prefisso dei dati di output impostato su `createJob`.
`output_data_bucket_name`	Stringa	Si tratta del bucket dei dati di output della tecnologia pubblicitaria in cui vengono archiviati i report di riepilogo generati. Questo campo è impostato su `createJob`.
`request_processing_started_at`	Stringa	L'ora in cui è iniziato l'ultimo tentativo di elaborazione. Sono esclusi i tempi di attesa nella coda dei job. (Tempo di elaborazione totale = `request_updated_at` - `request_processing_started_at`)
`result_info`	Dizionario	Si tratta del risultato della richiesta `createJob` e comprende tutte le informazioni disponibili. Vengono visualizzati i valori `return_code`, `return_message`, `finished_at` e `error_summary`.
`result_info.return_code`	Stringa	Il codice di ritorno del risultato del job. Queste informazioni sono necessarie per la risoluzione dei problemi relativi al servizio di aggregazione.
`result_info.return_message`	Stringa	Il messaggio di esito positivo o di errore restituito come risultato del job. Queste informazioni sono necessarie anche per la risoluzione dei problemi del servizio di aggregazione.
`result_info.error_summary`	Dizionario	Gli errori restituiti dal job. Questo contiene il numero di report e il tipo di errori riscontrati.
`result_info.finished_at`	Timestamp	Il timestamp che indica il completamento del job.
`result_info.error_summary.error_counts`	Elenco	Viene restituito un elenco dei messaggi di errore e il numero di report non riusciti con lo stesso messaggio di errore. Ogni conteggio degli errori contiene una categoria, `error_count` e `description`.
`result_info.error_summary.error_messages`	Elenco	Viene restituito un elenco dei messaggi di errore dei report di cui non è stato possibile completare l'elaborazione.
`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	Si escludono a vicenda con `reporting_site`. Si tratta dell'URL del report o dell'origine da cui è stato ricevuto. L'origine fa 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 in cui è stato ricevuto il report. L'origine fa 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 indicato in questo parametro. Questo valore è specificato nella richiesta `createJob`. Inoltre, assicurati che il bucket contenga solo i report che vuoi aggregare al momento della creazione del job. Tutti i report aggiunti al bucket di dati di input con origini report corrispondenti al sito di generazione di report specificato nel parametro del job vengono elaborati. Il servizio di aggregazione prende in considerazione solo i report all'interno del bucket di dati che corrispondono all'origine report registrata del job. Ad esempio, se l'origine registrata è https://exampleabc.com, vengono inclusi solo i report di https://exampleabc.com, anche se il bucket contiene report di sottodomini (`https://1.exampleabc.com` e così via) o domini completamente diversi (`https://3.examplexyz.com`).
`job_parameters.debug_privacy_epsilon`	Virgola mobile, Doppio	Campo facoltativo. Se non viene passato alcun valore, viene utilizzato il valore predefinito 10. I valori possono variare da 0 a 64. Questo valore è specificato nella richiesta `createJob`.
`job_parameters.report_error_threshold_percentage`	Doppio	Campo facoltativo. Si tratta della percentuale di report che può non riuscire prima del fallimento del job. Se non viene assegnato alcun valore, viene utilizzato il valore predefinito del 10%. Questo valore è specificato nella richiesta `createJob`.
`job_parameters.input_report_count`	Valore lungo	Campo facoltativo. Il numero totale di report forniti come dati di input per questo job. Il valore "report_error_threshold_percentage", combinato con questo valore, attiva l'interruzione anticipata del job se un numero significativo di report viene escluso a causa di errori. Questa impostazione viene specificata 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 vengono filtrati. Questo valore è specificato nella richiesta `createJob`. (ad es. `"filtering_ids":"12345,34455,12"`. Il valore predefinito è "0".)