Halaman ini diterjemahkan oleh Cloud Translation API.

Men-deploy dan mengelola permintaan dengan Layanan Agregasi

Setelah berhasil men-deploy Layanan Agregasi, Anda dapat menggunakan endpoint createJob dan getJob untuk berinteraksi dengan layanan. Diagram berikut memberikan representasi visual arsitektur deployment untuk kedua endpoint ini:

**Gambar 1.**Ringkasan Aggregation Service API

Anda dapat membaca lebih lanjut endpoint createJob dan getJob di dokumentasi Aggregation Service API.

Buat tugas

Untuk membuat tugas, kirim permintaan POST ke endpoint createJob. bash POST https://<api-gateway>/stage/v1alpha/createJob -+ Contoh isi permintaan untuk 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>"
  }
}

Pembuatan tugas yang berhasil akan menghasilkan kode status HTTP 202.

Perhatikan bahwa reporting_site dan attribution_report_to tidak dapat terjadi secara bersamaan dan hanya satu yang diperlukan.

Anda juga dapat meminta tugas debug dengan menambahkan debug_run ke job_parameters. Untuk informasi lebih lanjut tentang mode debug, lihat dokumentasi proses debug agregasi.

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

Kolom permintaan

Parameter	Jenis	Deskripsi
`job_request_id`	String	Ini adalah ID unik yang dibuat teknologi iklan yang harus berupa huruf ASCII dengan 128 karakter atau kurang. Tindakan ini mengidentifikasi permintaan tugas batch dan mengambil semua laporan AVRO agregat yang ditentukan dalam `input_data_blob_prefix` dari bucket input yang ditentukan dalam `input_data_bucket_name` yang dihosting di penyimpanan cloud teknologi iklan. Karakter: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
`input_data_blob_prefix`	String	Ini adalah jalur bucket. Untuk satu file, Anda dapat menggunakan jalur. Untuk beberapa file, Anda dapat menggunakan awalan di jalur. Contoh: Folder/file mengumpulkan semua laporan dari folder/file1.avro, folder/file/file1.avro, dan folder/file1/test/file2.avro.
`input_data_bucket_name`	String	Ini adalah bucket penyimpanan untuk data input atau laporan agregat. Data ini disimpan di penyimpanan cloud teknologi iklan.
`output_data_blob_prefix`	String	Ini adalah jalur output di bucket. Satu file output didukung.
`output_data_bucket_name`	String	Ini adalah bucket penyimpanan tempat `output_data` dikirim. Data ini ada di penyimpanan cloud teknologi iklan.
`job_parameters`	Kamus	Bidang wajib diisi. Kolom ini berisi berbagai kolom seperti: `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	Serupa dengan `input_data_blob_prefix`, ini adalah jalur di `output_domain_bucket_name` tempat AVRO domain output Anda berada. Untuk beberapa file, Anda dapat menggunakan awalan di jalur. Setelah Layanan Agregasi menyelesaikan batch, laporan ringkasan akan dibuat dan ditempatkan di bucket output `output_data_bucket_name` dengan nama `output_data_blob_prefix`.
`job_parameters.output_domain_bucket_name`	String	Ini adalah bucket penyimpanan untuk file AVRO domain output Anda. Data ini disimpan di penyimpanan cloud teknologi iklan.
`job_parameters.attribution_report_to`	String	Nilai ini saling eksklusif dengan `reporting_site`. Ini adalah URL pelaporan atau asal pelaporan tempat laporan diterima. Asal situs didaftarkan di Orientasi Layanan Agregasi.
`job_parameters.reporting_site`	String	Tidak dapat muncul bersamaan dengan `attribution_report_to`. Ini adalah nama host URL pelaporan atau asal pelaporan tempat laporan diterima. Asal situs didaftarkan di Orientasi Layanan Agregasi. Catatan: Anda dapat mengirimkan beberapa laporan dengan asal yang berbeda dalam satu permintaan, asalkan semua asal berasal dari situs pelaporan yang sama yang ditentukan dalam parameter ini.
`job_parameters.debug_privacy_epsilon`	Floating point, Ganda	Kolom opsional. Jika tidak ada nilai yang diteruskan, nilai defaultnya adalah 10. Nilai dari 0 hingga 64 dapat digunakan.
`job_parameters.report_error_threshold_percentage`	Ganda	Kolom opsional. Ini adalah persentase maksimum laporan yang gagal yang diizinkan sebelum tugas gagal. Jika dibiarkan kosong, nilai defaultnya adalah 10%.
`job_parameters.input_report_count`	nilai panjang	Kolom opsional. Jumlah total laporan yang diberikan sebagai data input untuk tugas. Nilai ini, bersama dengan `report_error_threshold_percentage`, memungkinkan kegagalan tugas awal saat laporan dikecualikan karena error.
`job_parameters.filtering_ids`	String	Kolom opsional. Daftar ID pemfilteran yang tidak ditandatangani yang dipisahkan koma. Semua kontribusi selain ID pemfilteran yang cocok akan difilter. (misalnya,`"filtering_ids": "12345,34455,12"`). Nilai defaultnya adalah 0.
`job_parameters.debug_run`	Boolean	Kolom opsional. Saat menjalankan debug, laporan dan anotasi ringkasan debug yang berisi derau dan tidak berisi derau akan ditambahkan untuk menunjukkan kunci mana yang ada di input dan/atau laporan domain. Selain itu, duplikat di seluruh batch juga tidak diterapkan. Perhatikan bahwa debug yang dijalankan hanya mempertimbangkan laporan yang memiliki tanda `"debug_mode": "enabled"`. Mulai v2.10.0, debug yang berjalan tidak menggunakan anggaran privasi.

Mendapatkan tugas

Saat teknologi iklan ingin mengetahui status batch yang diminta, mereka dapat memanggil endpoint getJob. Endpoint getJob dipanggil menggunakan permintaan HTTPS GET bersama dengan parameter job_request_id.

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

Anda akan mendapatkan respons yang menampilkan status tugas beserta pesan error:

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

Kolom respons

Parameter	Jenis	Deskripsi
`job_request_id`	String	Ini adalah ID tugas/batch unik yang ditentukan dalam permintaan `createJob`.
`job_status`	String	Ini adalah status permintaan tugas.
`request_received_at`	String	Waktu permintaan diterima.
`request_updated_at`	String	Waktu tugas terakhir diperbarui.
`input_data_blob_prefix`	String	Ini adalah awalan data input yang ditetapkan di `createJob`.
`input_data_bucket_name`	String	Ini adalah bucket data input teknologi iklan tempat laporan agregat disimpan. Kolom ini ditetapkan di `createJob`.
`output_data_blob_prefix`	String	Ini adalah awalan data output yang ditetapkan di `createJob`.
`output_data_bucket_name`	String	Ini adalah bucket data output teknologi iklan tempat laporan ringkasan yang dihasilkan disimpan. Kolom ini ditetapkan di `createJob`.
`request_processing_started_at`	String	Waktu saat upaya pemrosesan terbaru dimulai. Hal ini tidak termasuk waktu tunggu dalam antrean tugas. (Total waktu pemrosesan = `request_updated_at` - `request_processing_started_at`)
`result_info`	Kamus	Ini adalah hasil permintaan `createJob` dan terdiri dari semua informasi yang tersedia. Tindakan ini akan menampilkan nilai `return_code`, `return_message`, `finished_at`, dan `error_summary`.
`result_info.return_code`	String	Kode hasil yang ditampilkan tugas. Informasi ini diperlukan untuk memecahkan masalah jika ada masalah di Layanan Agregasi.
`result_info.return_message`	String	Pesan berhasil atau gagal yang ditampilkan sebagai hasil tugas. Informasi ini juga diperlukan untuk memecahkan masalah Layanan Agregasi.
`result_info.error_summary`	Kamus	Error yang ditampilkan dari tugas. Bagian ini berisi jumlah laporan beserta jenis error yang ditemukan.
`result_info.finished_at`	Stempel waktu	Stempel waktu yang menunjukkan penyelesaian tugas.
`result_info.error_summary.error_counts`	Daftar	Tindakan ini akan menampilkan daftar pesan error beserta jumlah laporan yang gagal dengan pesan error yang sama. Setiap jumlah error berisi kategori, `error_count`,dan `description`.
`result_info.error_summary.error_messages`	Daftar	Tindakan ini akan menampilkan daftar pesan error dari laporan yang gagal diproses.
`job_parameters`	Kamus	Ini berisi parameter tugas yang diberikan dalam permintaan `createJob`. Properti yang relevan seperti `output_domain_blob_prefix` dan `output_domain_bucket_name`.
`job_parameters.attribution_report_to`	String	Tidak dapat muncul bersamaan dengan `reporting_site`. Ini adalah URL pelaporan atau asal tempat laporan diterima. Asal adalah bagian dari situs yang terdaftar di Orientasi Layanan Agregasi. Hal ini ditentukan dalam permintaan `createJob`.
`job_parameters.reporting_site`	String	Tidak dapat muncul bersamaan dengan `attribution_report_to`. Ini adalah nama host URL pelaporan atau asal tempat laporan diterima. Asal adalah bagian dari situs yang terdaftar di Orientasi Layanan Agregasi. Perhatikan bahwa Anda dapat mengirimkan laporan dengan beberapa origin pelaporan dalam permintaan yang sama selama semua origin pelaporan berasal dari situs yang sama yang disebutkan dalam parameter ini. Hal ini ditentukan dalam permintaan `createJob`. Selain itu, pastikan bucket hanya berisi laporan yang ingin Anda gabungkan pada saat pembuatan tugas. Semua laporan yang ditambahkan ke bucket data input dengan asal pelaporan yang cocok dengan situs pelaporan yang ditentukan dalam parameter tugas akan diproses. Layanan Agregasi hanya mempertimbangkan laporan dalam bucket data yang cocok dengan asal pelaporan terdaftar tugas. Misalnya, jika origin terdaftar adalah https://exampleabc.com, hanya laporan dari https://exampleabc.com yang disertakan, meskipun bucket berisi laporan dari subdomain (`https://1.exampleabc.com`, dll.) atau domain yang sama sekali berbeda (`https://3.examplexyz.com`).
`job_parameters.debug_privacy_epsilon`	Floating point, Ganda	Kolom opsional. Jika tidak ada nilai yang diteruskan, nilai default 10 akan digunakan. Nilai dapat berkisar dari 0 hingga 64. Nilai ini ditentukan dalam permintaan `createJob`.
`job_parameters.report_error_threshold_percentage`	Ganda	Kolom opsional. Ini adalah persentase nilai minimum laporan yang dapat gagal sebelum kegagalan tugas. Jika tidak ada nilai yang ditetapkan, nilai default 10% akan digunakan. Hal ini ditentukan dalam permintaan `createJob`.
`job_parameters.input_report_count`	Nilai panjang	Kolom opsional. Jumlah total laporan yang diberikan sebagai data input untuk tugas ini. `report_error_threshold_percentage`, yang dikombinasikan dengan nilai ini, memicu kegagalan tugas awal jika sejumlah besar laporan dikecualikan karena error. Setelan ini ditentukan dalam permintaan `createJob`.
`job_parameters.filtering_ids`	String	Kolom opsional. Daftar ID pemfilteran yang tidak ditandatangani yang dipisahkan koma. Semua kontribusi selain ID pemfilteran yang cocok akan difilter. Hal ini ditentukan dalam permintaan `createJob`. (misalnya, `"filtering_ids":"12345,34455,12"`. Nilai defaultnya adalah "0".)