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 dari arsitektur deployment untuk kedua endpoint ini:

Ringkasan Aggregation Service API
Gambar 1.Ringkasan API Layanan Agregasi

Anda dapat membaca lebih lanjut tentang 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 bersamaan dan hanya salah satunya yang diperlukan.

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

{
  "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 yang dapat diagregasi 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 file tunggal, 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 gabungan. Ini ada 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. File 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 Mirip 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. Ini ada di penyimpanan cloud teknologi iklan.
job_parameters.attribution_report_to String Nilai ini tidak dapat digunakan bersamaan dengan `reporting_site`. Ini adalah URL pelaporan atau asal pelaporan tempat laporan diterima. Origin situs terdaftar di Pengaktifan 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. Origin situs terdaftar di Pengaktifan Layanan Agregasi. Catatan: Anda dapat mengirimkan beberapa laporan dengan asal yang berbeda dalam satu permintaan, asalkan semua asal termasuk dalam situs pelaporan yang sama yang ditentukan dalam parameter ini.
job_parameters.debug_privacy_epsilon Floating point, Double 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 lebih awal saat laporan dikecualikan karena error.
job_parameters.filtering_ids String Kolom opsional. Daftar ID pemfilteran yang tidak bertanda tangan yang dipisahkan dengan 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 proses debug, laporan ringkasan dan anotasi debug yang diberi derau dan tidak diberi derau ditambahkan untuk menunjukkan kunci mana yang ada dalam input dan/atau laporan domain. Selain itu, duplikat di seluruh batch juga tidak diterapkan. Perhatikan bahwa proses debug hanya mempertimbangkan laporan yang memiliki tanda "debug_mode": "enabled". Mulai v2.10.0, proses debug >tidak menggunakan anggaran privasi.

Mendapatkan tugas

Jika ingin mengetahui status batch yang diminta, teknologi iklan dapat memanggil endpoint getJob. Endpoint getJob dipanggil menggunakan permintaan GET HTTPS 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 saat 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. Ini tidak termasuk waktu menunggu 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. Ini menampilkan nilai return_code, return_message, finished_at, dan error_summary.
result_info.return_code String Kode hasil 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 terjadi.
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. Origin adalah bagian dari situs yang terdaftar dalam Pengaktifan 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. Origin adalah bagian dari situs yang terdaftar dalam Pengaktifan Layanan Agregasi. Perhatikan bahwa Anda dapat mengirimkan laporan dengan beberapa asal pelaporan dalam permintaan yang sama selama semua asal pelaporan termasuk dalam 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. Laporan apa pun 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 origin pelaporan terdaftar tugas. Misalnya, jika asal yang 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, Double 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 minimum laporan yang dapat gagal sebelum tugas gagal. 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, akan memicu kegagalan tugas lebih 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 dengan 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".)