Toplama Hizmeti'ni başarıyla dağıttıktan sonra hizmetle etkileşim kurmak için createJob ve getJob uç noktalarını kullanabilirsiniz. Aşağıdaki şemada, bu iki uç nokta için dağıtım mimarisinin görsel bir temsili verilmiştir:
createJob ve getJob uç noktaları hakkında daha fazla bilgiyi Aggregation Service API belgelerinde bulabilirsiniz.
İş oluşturun
İş oluşturmak için createJob uç noktasına bir POST isteği gönderin.
bash
POST https://<api-gateway>/stage/v1alpha/createJob
-+
createJob için istek metnine örnek:
{
"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>"
}
}
Başarılı bir iş oluşturma işlemi 202 HTTP durum koduyla sonuçlanır.
reporting_site ve attribution_report_to'nin birbirini dışladığını ve yalnızca birinin gerekli olduğunu unutmayın.
debug_run öğesini job_parameters içine ekleyerek hata ayıklama işi de isteyebilirsiniz.
Hata ayıklama modu hakkında daha fazla bilgi için toplama hata ayıklama çalıştırma dokümanımızı inceleyin.
{
"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"
}
}
İstek alanları
| Parametre | Tür | Açıklama |
|---|---|---|
job_request_id |
Dize |
Bu, reklam teknolojisi tarafından oluşturulan benzersiz bir tanımlayıcıdır ve 128 karakterden kısa ASCII harflerinden oluşmalıdır. Bu, toplu iş isteğini tanımlar ve reklam teknolojisinin bulut depolama alanında barındırılan, `input_data_bucket_name` içinde belirtilen giriş paketinden `input_data_blob_prefix` içinde belirtilen tüm toplanabilir AVRO raporlarını alır.
Karakterler: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
|
input_data_blob_prefix |
Dize |
Bu, paket yolu. Tek dosyalar için yolu kullanabilirsiniz. Birden fazla dosya için yoldaki öneki kullanabilirsiniz.
Örnek: Klasör/dosya, folder/file1.avro, folder/file/file1.avro ve folder/file1/test/file2.avro dosyalarındaki tüm raporları toplar. |
input_data_bucket_name |
Dize | Bu, giriş verileri veya toplanabilir raporlar için depolama paketi. Bu, reklam teknolojisi sağlayıcının bulut depolama alanında yer alır. |
output_data_blob_prefix |
Dize | Bu, paketteki çıkış yoludur. Tek bir çıkış dosyası desteklenir. |
output_data_bucket_name |
Dize |
Bu, output_data öğesinin gönderildiği depolama paketidir. Bu, reklam teknolojisinin bulut depolama alanında bulunur.
|
job_parameters |
Sözlük |
Zorunlu alan. Bu alan, aşağıdakiler gibi farklı alanları içerir:
|
job_parameters.output_domain_blob_prefix |
Dize |
input_data_blob_prefix'ya benzer şekilde, bu, çıkış alanı AVRO'nuzun bulunduğu output_domain_bucket_name içindeki yoldur. Birden fazla dosya için yoldaki öneki kullanabilirsiniz. Toplama Hizmeti grubu tamamladığında özet rapor oluşturulur ve output_data_blob_prefix adıyla çıkış paketine output_data_bucket_name yerleştirilir.
|
job_parameters.output_domain_bucket_name |
Dize | Bu, çıkış alanı AVRO dosyanızın depolama paketi. Bu, reklam teknolojisi sağlayıcının bulut depolama alanında yer alır. |
job_parameters.attribution_report_to |
Dize | Bu değer, "reporting_site" ile karşılıklı olarak hariç tutulur. Bu, raporun alındığı raporlama URL'si veya raporlama kaynağıdır. Site kaynağı, Aggregation Service Onboarding'e kaydedilir. |
job_parameters.reporting_site |
Dize |
attribution_report_to ile karşılıklı olarak birbirini dışlar. Bu, raporun alındığı raporlama URL'sinin veya raporlama kaynağının ana makine adıdır. Site kaynağı, Aggregation Service Onboarding'e kaydedilir.
Not: Tüm kaynaklar bu parametrede belirtilen aynı raporlama sitesine ait olmak koşuluyla, tek bir istekte farklı kaynaklara sahip birden fazla rapor gönderebilirsiniz.
|
job_parameters.debug_privacy_epsilon |
Kayan nokta, Çift | İsteğe bağlı alan. Değer iletilmezse varsayılan değer 10 olur. 0 ile 64 arasında bir değer kullanılabilir. |
job_parameters.report_error_threshold_percentage |
Çift | İsteğe bağlı alan. Bu, işin başarısız olması için izin verilen maksimum başarısız rapor yüzdesidir. Boş bırakılırsa varsayılan değer %10'dur. |
job_parameters.input_report_count |
uzun değer |
İsteğe bağlı alan. İş için giriş verileri olarak sağlanan raporların toplam sayısı. Bu değer, report_error_threshold_percentage ile birlikte kullanıldığında raporlar hatalar nedeniyle hariç tutulduğunda işin erken aşamada başarısız olmasını sağlar.
|
job_parameters.filtering_ids |
Dize |
İsteğe bağlı alan. Virgülle ayrılmış, imzalanmamış filtreleme kimliklerinin listesi. Eşleşen filtreleme kimliği dışındaki tüm katkılar filtrelenir. (ör."filtering_ids": "12345,34455,12"). Varsayılan değer 0'dır.
|
job_parameters.debug_run |
Boole |
İsteğe bağlı alan. Hata ayıklama çalıştırması yürütülürken, hangi anahtarların alan girişinde ve/veya raporlarda bulunduğunu belirtmek için gürültü eklenmiş ve gürültü eklenmemiş hata ayıklama özeti raporları ve ek açıklamalar eklenir. Ayrıca, toplu işlemler arasında yinelenen öğeler de zorunlu kılınmaz. Hata ayıklama çalıştırmasında yalnızca "debug_mode": "enabled" işaretine sahip raporların dikkate alındığını unutmayın. v2.10.0'dan itibaren hata ayıklama çalıştırmaları gizlilik bütçesini kullanmaz.
|
İş bulma
Bir reklam teknolojisi şirketi, istenen bir toplu işlemin durumunu öğrenmek istediğinde getJob uç noktasını çağırabilir. getJob uç noktası, job_request_id parametresiyle birlikte bir HTTPS GET isteği kullanılarak çağrılır.
GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>
İş durumuyla birlikte hata mesajlarını içeren bir yanıt alırsınız:
{
"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"
}
Yanıt alanları
| Parametre | Tür | Açıklama |
|---|---|---|
job_request_id |
Dize |
Bu, createJob isteğinde belirtilen benzersiz iş/toplu iş kimliğidir.
|
job_status |
Dize | Bu, iş isteğinin durumudur. |
request_received_at |
Dize | İsteğin alındığı zaman. |
request_updated_at |
Dize | İşin son güncellenme zamanı. |
input_data_blob_prefix |
Dize |
Bu, createJob konumunda ayarlanan giriş verileri önekidir.
|
input_data_bucket_name |
Dize |
Bu, toplanabilir raporların depolandığı reklam teknolojisinin giriş verileri paketidir. Bu alan createJob olarak ayarlanmıştır.
|
output_data_blob_prefix |
Dize |
Bu, createJob tarihinde ayarlanan çıkış verileri önekidir.
|
output_data_bucket_name |
Dize |
Bu, oluşturulan özet raporların depolandığı reklam teknolojisinin çıkış verileri paketidir. Bu alan createJob olarak ayarlanmıştır.
|
request_processing_started_at |
Dize |
En son işleme girişiminin başladığı zaman. Bu süreye iş sırasındaki bekleme süresi dahil değildir.
(Toplam işleme süresi = request_updated_at - request_processing_started_at)
|
result_info |
Sözlük |
Bu, createJob isteğinin sonucudur ve mevcut tüm bilgileri içerir.
Bu değerler return_code, return_message, finished_at ve error_summary değerlerini gösterir.
|
result_info.return_code |
Dize | İş sonucu dönüş kodu. Toplama hizmetinde bir sorun olması durumunda sorun giderme için bu bilgiler gereklidir. |
result_info.return_message |
Dize | İşlem sonucunda döndürülen başarı veya hata mesajı. Bu bilgiler, Toplama Hizmeti sorunlarını gidermek için de gereklidir. |
result_info.error_summary |
Sözlük | İşten döndürülen hatalar. Bu bölümde, karşılaşılan hata türleriyle birlikte rapor sayısı yer alır. |
result_info.finished_at |
Zaman damgası | İşin tamamlandığını gösteren zaman damgası. |
result_info.error_summary.error_counts |
Liste |
Bu işlev, hata mesajlarının listesini ve aynı hata mesajıyla başarısız olan raporların sayısını döndürür. Her hata sayısında bir kategori, error_count ve description bulunur.
|
result_info.error_summary.error_messages |
Liste | Bu işlev, işlenemeyen raporlardaki hata mesajlarının listesini döndürür. |
job_parameters |
Sözlük |
Bu, createJob isteğinde sağlanan iş parametrelerini içerir. `output_domain_blob_prefix` ve `output_domain_bucket_name` gibi alakalı özellikler.
|
job_parameters.attribution_report_to |
Dize |
reporting_site ile karşılıklı olarak birbirini dışlar. Bu, raporlama URL'si veya raporun alındığı kaynak konumdur. Kaynak, Aggregation Service Onboarding'e kaydedilen sitenin bir parçasıdır. Bu, createJob isteğinde belirtilir.
|
job_parameters.reporting_site |
Dize |
attribution_report_to ile karşılıklı olarak birbirini dışlar. Bu, raporlama URL'sinin ana makine adı veya raporun alındığı kaynak. Kaynak, Aggregation Service Onboarding'e kaydedilen sitenin bir parçasıdır. Tüm raporlama kaynakları bu parametrede belirtilen aynı siteye ait olduğu sürece aynı istekte birden fazla raporlama kaynağı içeren raporlar gönderebileceğinizi unutmayın. Bu, createJob isteğinde belirtilir. Ayrıca, paketin yalnızca iş oluşturma sırasında birleştirilmesini istediğiniz raporları içerdiğini doğrulayın. İş parametresinde belirtilen raporlama sitesiyle eşleşen raporlama kaynaklarına sahip giriş verileri paketine eklenen tüm raporlar işlenir.
Toplama Hizmeti yalnızca işin kayıtlı raporlama kaynağıyla eşleşen veri paketindeki raporları dikkate alır. Örneğin, kayıtlı kaynak https://exampleabc.com ise alt alan adlarından (https://1.exampleabc.com vb.) veya tamamen farklı alan adlarından (https://3.examplexyz.com) gelen raporlar kovada bulunsa bile yalnızca https://exampleabc.com adresinden gelen raporlar dahil edilir.
|
job_parameters.debug_privacy_epsilon |
Kayan nokta, Çift |
İsteğe bağlı alan. Değer iletilmezse varsayılan değer olan 10 kullanılır. Değerler 0 ile 64 arasında olabilir. Bu değer, createJob isteğinde belirtilir.
|
job_parameters.report_error_threshold_percentage |
Çift |
İsteğe bağlı alan. Bu, işin başarısız olmasından önce başarısız olabilecek raporların eşik yüzdesidir. Değer atanmazsa% 10 olan varsayılan değer kullanılır. Bu, createJob isteğinde belirtilir.
|
job_parameters.input_report_count |
Uzun değer | İsteğe bağlı alan. Bu iş için giriş verileri olarak sağlanan toplam rapor sayısı. Bu değerle birlikte kullanılan `report_error_threshold_percentage`, hatalar nedeniyle önemli sayıda rapor hariç tutulursa işin erken başarısız olmasına neden olur. Bu ayar, `createJob` isteğinde belirtilir. |
job_parameters.filtering_ids |
Dize |
İsteğe bağlı alan. Virgülle ayrılmış, imzalanmamış filtreleme kimliklerinin listesi. Eşleşen filtreleme kimliği dışındaki tüm katkılar filtrelenir. Bu, createJob isteğinde belirtilir.
(ör. "filtering_ids":"12345,34455,12". Varsayılan değer "0"dır.)
|