Diese Seite wurde von der Cloud Translation API übersetzt.

Anfragen mit dem Aggregationsdienst bereitstellen und verwalten

Nachdem Sie den Aggregationsdienst bereitgestellt haben, können Sie über die Endpunkte createJob und getJob mit dem Dienst interagieren. Das folgende Diagramm zeigt die Bereitstellungsarchitektur für diese beiden Endpunkte:

**Abbildung 1:**Aggregation Service API – Übersicht

Weitere Informationen zu den Endpunkten createJob und getJob finden Sie in der Dokumentation zur Aggregation Service API.

Job erstellen

Senden Sie zum Erstellen eines Jobs eine POST-Anfrage an den Endpunkt createJob. bash POST https://<api-gateway>/stage/v1alpha/createJob -+ Beispiel für den Anfragetext für 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>"
  }
}

Bei einer erfolgreichen Joberstellung wird der HTTP-Statuscode 202 zurückgegeben.

reporting_site und attribution_report_to schließen sich gegenseitig aus und nur eines ist erforderlich.

Sie können auch einen Debug-Job anfordern, indem Sie debug_run in die job_parameters einfügen. Weitere Informationen zum Debug-Modus finden Sie in der Dokumentation zur Aggregations-Debug-Ausführung.

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

Anfragefelder

Parameter	Typ	Beschreibung
`job_request_id`	String	Dies ist eine eindeutige Kennung, die von der Anzeigentechnologie generiert wird. Sie sollte aus ASCII-Buchstaben mit maximal 128 Zeichen bestehen. Dadurch wird die Batchjobanfrage identifiziert und alle aggregierbaren AVRO-Berichte, die im „input_data_blob_prefix“ angegeben sind, werden aus dem Eingabe-Bucket im „input_data_bucket_name“ abgerufen, der im Cloud Storage der Anzeigentechnologie gehostet wird. Zeichen: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
`input_data_blob_prefix`	String	Dies ist der Bucket-Pfad. Bei einzelnen Dateien können Sie den Pfad verwenden. Bei mehreren Dateien können Sie das Präfix im Pfad verwenden. Beispiel: Im Ordner/in der Datei werden alle Berichte aus den Dateien „Ordner/Datei1.avro“, „Ordner/Datei/Datei1.avro“ und „Ordner/Datei1/Test/Datei2.avro“ erfasst.
`input_data_bucket_name`	String	Dies ist der Speicher-Bucket für die Eingabedaten oder aggregierbaren Berichte. Diese Daten befinden sich im Cloud-Speicher der Anzeigentechnologie.
`output_data_blob_prefix`	String	Dies ist der Ausgabepfad im Bucket. Es wird nur eine Ausgabedatei unterstützt.
`output_data_bucket_name`	String	Dies ist der Speicher-Bucket, in den die `output_data` gesendet wird. Dieser befindet sich im Cloud-Speicher der Anzeigentechnologie.
`job_parameters`	Wörterbuch	Pflichtfeld. Dieses Feld enthält verschiedene Felder, z. B.: `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`	String	Ähnlich wie bei `input_data_blob_prefix` ist dies der Pfad in `output_domain_bucket_name`, unter dem sich die Ausgabedomain „AVRO“ befindet. Bei mehreren Dateien können Sie das Präfix im Pfad verwenden. Sobald der Aggregationsdienst den Batch abgeschlossen hat, wird der Zusammenfassungsbericht erstellt und mit dem Namen `output_data_blob_prefix` im Ausgabe-Bucket `output_data_bucket_name` abgelegt.
`job_parameters.output_domain_bucket_name`	String	Dies ist der Speicher-Bucket für die AVRO-Datei Ihrer Ausgabedomain. Diese Daten befinden sich im Cloud-Speicher der Anzeigentechnologie.
`job_parameters.attribution_report_to`	String	Dieser Wert ist mit „reporting_site“ nicht kompatibel. Es handelt sich um die URL oder den Ursprung der Meldung, über die der Bericht empfangen wurde. Der Websiteursprung ist beim Onboarding des Aggregationsdienstes registriert.
`job_parameters.reporting_site`	String	Schließt sich mit `attribution_report_to` gegenseitig aus. Dies ist der Hostname der URL oder des Ursprungs der Meldung, über die der Bericht empfangen wurde. Der Websiteursprung ist beim Onboarding des Aggregationsdienstes registriert. Hinweis: Sie können mehrere Berichte mit unterschiedlichen Ursprüngen in einer einzigen Anfrage einreichen, sofern alle Ursprünge zu der in diesem Parameter angegebenen Meldestelle gehören.
`job_parameters.debug_privacy_epsilon`	Gleitkomma, doppelt	Optionales Feld. Wenn kein Wert übergeben wird, ist der Standardwert 10. Es kann ein Wert zwischen 0 und 64 verwendet werden.
`job_parameters.report_error_threshold_percentage`	Doppelt	Optionales Feld. Dies ist der maximale Prozentsatz fehlgeschlagener Berichte, der zulässig ist, bevor der Job fehlschlägt. Wenn Sie dieses Feld leer lassen, wird der Standardwert 10 % verwendet.
`job_parameters.input_report_count`	Langer Wert	Optionales Feld. Die Gesamtzahl der Berichte, die als Eingabedaten für den Job bereitgestellt wurden. In Verbindung mit `report_error_threshold_percentage` ermöglicht dieser Wert einen frühzeitigen Jobfehler, wenn Berichte aufgrund von Fehlern ausgeschlossen werden.
`job_parameters.filtering_ids`	String	Optionales Feld. Eine Liste von nicht signierten Filter-IDs, durch Kommas getrennt. Alle Beiträge, die nicht mit der übereinstimmenden Filter-ID übereinstimmen, werden herausgefiltert. (z.B.`"filtering_ids": "12345,34455,12"`). Der Standardwert ist 0.
`job_parameters.debug_run`	Boolesch	Optionales Feld. Bei der Ausführung eines Debug-Laufs werden Berichte und Anmerkungen mit und ohne Rauschen hinzugefügt, um anzugeben, welche Schlüssel in der Domaineingabe und/oder in den Berichten vorhanden sind. Außerdem werden keine Duplikate zwischen Batches erzwungen. Bei der Debug-Ausführung werden nur Berichte berücksichtigt, die das Flag `"debug_mode": "enabled"` haben. Ab Version 2.10.0 wird das Privacy Budget bei Debug-Ausführungen nicht in Anspruch genommen.

Job abrufen

Wenn eine Anzeigentechnologie den Status eines angeforderten Batches erfahren möchte, kann sie den Endpunkt getJob aufrufen. Der getJob-Endpunkt wird mit einer HTTPS-GET-Anfrage und dem Parameter job_request_id aufgerufen.

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

Sie sollten eine Antwort erhalten, die den Jobstatus zusammen mit allen Fehlermeldungen zurückgibt:

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

Antwortfelder

Parameter	Typ	Beschreibung
`job_request_id`	String	Dies ist die eindeutige Job-/Batch-ID, die in der `createJob`-Anfrage angegeben wurde.
`job_status`	String	Dies ist der Status der Jobanfrage.
`request_received_at`	String	Der Zeitpunkt, zu dem die Anfrage empfangen wurde.
`request_updated_at`	String	Der Zeitpunkt, zu dem die Aufgabe zuletzt aktualisiert wurde.
`input_data_blob_prefix`	String	Das ist das Präfix für die Eingabedaten, das unter `createJob` festgelegt wurde.
`input_data_bucket_name`	String	Dies ist der Eingabedaten-Bucket der Anzeigentechnologie, in dem die aggregierbaren Berichte gespeichert werden. Dieses Feld ist auf `createJob` gesetzt.
`output_data_blob_prefix`	String	Das ist das Präfix für Ausgabedaten, das unter `createJob` festgelegt wurde.
`output_data_bucket_name`	String	Dies ist der Ausgabedaten-Bucket der Anzeigentechnologie, in dem die generierten Zusammenfassungsberichte gespeichert werden. Dieses Feld ist auf `createJob` gesetzt.
`request_processing_started_at`	String	Der Zeitpunkt, zu dem der letzte Verarbeitungsversuch gestartet wurde. Die Zeit, die in der Jobwarteschlange gewartet wird, ist nicht inbegriffen. (Gesamtverarbeitungszeit = `request_updated_at` – `request_processing_started_at`)
`result_info`	Wörterbuch	Dies ist das Ergebnis des `createJob`-Antrags und enthält alle verfügbaren Informationen. Hier sehen Sie die Werte `return_code`, `return_message`, `finished_at` und `error_summary`.
`result_info.return_code`	String	Der Rückgabecode des Jobergebnisses. Diese Informationen sind für die Fehlerbehebung bei Problemen mit dem Aggregationsdienst erforderlich.
`result_info.return_message`	String	Entweder die Erfolgs- oder die Fehlermeldung, die als Ergebnis des Jobs zurückgegeben wurde. Diese Informationen sind auch für die Fehlerbehebung bei Problemen mit dem Aggregationsdienst erforderlich.
`result_info.error_summary`	Wörterbuch	Die vom Job zurückgegebenen Fehler. Dieser enthält die Anzahl der Meldungen sowie die Art der Fehler.
`result_info.finished_at`	Zeitstempel	Der Zeitstempel für den Abschluss des Jobs.
`result_info.error_summary.error_counts`	Liste	Daraufhin wird eine Liste der Fehlermeldungen mit der Anzahl der Berichte zurückgegeben, die mit derselben Fehlermeldung fehlgeschlagen sind. Jede Fehleranzahl enthält eine Kategorie, `error_count` und `description`.
`result_info.error_summary.error_messages`	Liste	Daraufhin wird eine Liste der Fehlermeldungen für Berichte zurückgegeben, die nicht verarbeitet werden konnten.
`job_parameters`	Wörterbuch	Dieser enthält die Jobparameter, die in der `createJob`-Anfrage angegeben wurden. Relevante Properties wie „output_domain_blob_prefix“ und „output_domain_bucket_name“.
`job_parameters.attribution_report_to`	String	Schließt sich mit `reporting_site` gegenseitig aus. Dies ist die URL der Meldung oder der Ursprung, von dem aus die Meldung empfangen wurde. Der Ursprung ist Teil der Website, die im Onboarding des Aggregationsdienstes registriert ist. Dies wird in der `createJob`-Anfrage angegeben.
`job_parameters.reporting_site`	String	Schließt sich mit `attribution_report_to` gegenseitig aus. Dies ist der Hostname der Berichts-URL oder der Ursprung, von dem der Bericht empfangen wurde. Der Ursprung ist Teil der Website, die im Onboarding des Aggregationsdienstes registriert ist. Sie können Berichte mit mehreren Berichtsquellen in derselben Anfrage einreichen, sofern alle Berichtsquellen zu der in diesem Parameter genannten Website gehören. Dies wird in der `createJob`-Anfrage angegeben. Außerdem muss der Bucket zum Zeitpunkt der Joberstellung nur die Berichte enthalten, die Sie aggregieren möchten. Alle Berichte, die dem Eingabedaten-Bucket mit Berichtsquellen hinzugefügt wurden, die mit der im Jobparameter angegebenen Berichtswebsite übereinstimmen, werden verarbeitet. Der Aggregationsdienst berücksichtigt nur Berichte im Daten-Bucket, die mit dem registrierten Berichtsorigin des Jobs übereinstimmen. Wenn der registrierte Ursprung beispielsweise https://beispielabc.de ist, werden nur Berichte von https://beispielabc.de berücksichtigt, auch wenn der Bucket Berichte von Subdomains (`https://1.exampleabc.com` usw.) oder völlig anderen Domains (`https://3.examplexyz.com`) enthält.
`job_parameters.debug_privacy_epsilon`	Gleitkomma, doppelt	Optionales Feld. Wenn kein Wert übergeben wird, wird der Standardwert „10“ verwendet. Die Werte können zwischen 0 und 64 liegen. Dieser Wert wird in der `createJob`-Anfrage angegeben.
`job_parameters.report_error_threshold_percentage`	Doppelt	Optionales Feld. Das ist der Grenzwert für den Prozentsatz der Berichte, die fehlschlagen können, bevor der Job fehlschlägt. Wenn kein Wert zugewiesen ist, wird der Standardwert von 10% verwendet. Dies wird in der `createJob`-Anfrage angegeben.
`job_parameters.input_report_count`	Langer Wert	Optionales Feld. Die Gesamtzahl der Berichte, die als Eingabedaten für diesen Job bereitgestellt wurden. In Kombination mit diesem Wert löst der Parameter „report_error_threshold_percentage“ einen vorzeitigen Jobfehler aus, wenn eine erhebliche Anzahl von Berichten aufgrund von Fehlern ausgeschlossen wird. Diese Einstellung wird in der Anfrage „createJob“ angegeben.
`job_parameters.filtering_ids`	String	Optionales Feld. Eine Liste von nicht signierten Filter-IDs, durch Kommas getrennt. Alle Beiträge, die nicht mit der Filter-ID übereinstimmen, werden herausgefiltert. Dies wird in der `createJob`-Anfrage angegeben. (z.B. `"filtering_ids":"12345,34455,12"`. Der Standardwert ist „0“.)