Aggregation Service API'yi anlama

Dağıtımdan sonra Toplama Hizmeti, reklam teknolojisi kullanımı için iki uç nokta sunar: createJob ve getJob.

AgS Diyagramı

createJob ve getJob uç noktaları hakkında daha fazla bilgiyi Aggregation Service API belgelerinde bulabilirsiniz.

createJob

createJob uç noktası, bir HTTP POST isteği aracılığıyla çağrılır ve istek gövdesi gerektirir. createJob isteği yapıldıktan sonra HTTP 202 başarı yanıtı alırsınız.

  POST https://<api-gateway>/stage/v1alpha/createJob

createJob için istek gövdesi örneği:

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

reporting_site ve attribution_report_to'ün birbirini hariç tuttuğunu ve yalnızca birinin gerekli olduğunu unutmayın.

job_parameters alanına debug_run ekleyerek de hata ayıklama işi isteğinde bulunabilirsiniz. Hata ayıklama modunu anlamak için toplama hata ayıklama çalıştırma dokümanlarımıza göz atın.

{
  "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 ve 128 karakter veya daha kısa ASCII harflerinden oluşan benzersiz bir tanımlayıcıdır. Bu, toplu iş isteğini tanımlar ve reklam teknolojisinin bulut depolama alanında barındırılan giriş_data_bucket_name öğesinde belirtilen giriş paketinden "input_data_blob_prefix" parametresinde belirtilen tüm toplanabilir avro raporlarını alır.
Karakter sayısı: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix Dize Bu, paketteki yoldur. Tek dosyalar için yolu kullanabilirsiniz. Birden fazla dosya için yoldaki ön eki kullanabilirsiniz.
Örnek: klasör/dosya, tüm raporları "klasor/dosya1.avro", "klasor/dosya/dosya1.avro", "klasor/dosya1/test/dosya2.avro"dan toplar.
input_data_bucket_name Dize Bu, giriş verileri veya toplanabilir raporlar için depolama paketidir. Bu öğe, reklam teknolojisinin bulut depolama alanında yer alıyor.
output_data_blob_prefix Dize Bu, paketteki çıkış yoludur. Tek çıkış dosyası desteklenir.
output_data_bucket_name Dize Bu, output_data öğesinin gönderileceği depolama paketidir. Bu öğe, reklam teknolojisinin bulut depolama alanında yer alıyor.
job_parameters Sözlük Zorunlu alan. Bu bölümde aşağıdakiler gibi farklı alanlar yer alır:
  • 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 Dize input_data_blob_prefix özelliğine benzer şekilde, bu da AVRO çıkış alan adınızın bulunduğu output_domain_bucket_name yolu olacaktır. Birden fazla dosya için yoldaki öneki kullanabilirsiniz. Toplama Hizmeti grubu tamamladıktan sonra özet rapor oluşturulur ve output_data_blob_prefix adıyla output_data_bucket_name çıkış paketine yerleştirilir.
job_parameters.output_domain_bucket_name Dize Bu, çıkış alan adınızın AVRO dosyasının depolama paketidir. Bu öğe, reklam teknolojisinin bulut depolama alanında yer alıyor.
job_parameters.attribution_report_to Dize reporting_site ile birbirini dışlar. Bu, raporun alındığı raporlama URL'si veya raporlama kaynağıdır. Kaynak, Toplama Hizmeti İlk Kayıt'ına kaydedilen sitenin bir parçası olacaktır.
job_parameters.reporting_site Dize attribution_report_to ile birbirini dışlar. Bu, raporlama URL'sinin veya raporun alındığı raporlama kaynağının ana makine adıdır. Kaynak, Toplama Hizmeti İlk Katılımı'nda kayıtlı olan sitenin bir parçasıdır. Not: Tüm raporlama kaynakları bu parametrede belirtilen raporlama sitesine ait olduğu sürece aynı istekte birden fazla raporlama kaynağı içeren raporlar gönderebilirsiniz.
job_parameters.debug_privacy_epsilon Kayan nokta, Çift İsteğe bağlı alandır. Hiçbiri iletilmediyse varsayılan değer 10'dur. 0-64 arasında bir değer kullanılabilir. Değer değişebilir.
job_parameters.report_error_threshold_percentage Çift İsteğe bağlı alan. Bu, iş başarısız olmaya başlamadan önce başarısız olabilecek raporların yüzdesi eşiğidir. Boş bırakılırsa varsayılan olarak %10 kullanılır.
job_parameters.input_report_count uzun değer İsteğe bağlı alan. Bu iş için giriş verisi olarak sağlanan toplam rapor sayısı. Bu değer, report_error_threshold_percentage ile birlikte, raporlar hatalar nedeniyle hariç tutulduğunda işin erken başarısız olmasını sağlar.
job_parameters.filtering_ids Dize İsteğe bağlı alan. İmzasız filtreleme kimliklerinin virgülle ayrılmış 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 işlemi gerçekleştirilirken gürültülü ve gürültüsüz hata ayıklama özeti raporları ile ek açıklamalar, alan girişinde ve/veya raporlarında hangi anahtarların bulunduğunu gösterir. Ayrıca, gruplardaki yinelemeler de zorunlu kılınmaz. Hata ayıklama çalıştırmasının yalnızca "debug_mode": "enabled" işaretine sahip raporları dikkate aldığını ve hata ayıklama çalıştırmalarının bütçeyi tükettiğini unutmayın.

getJob

Reklam teknolojisi, istenen bir toplu işin durumunu öğrenmek istediğinde getJob uç noktasını çağırabilir. getJob uç noktası, istekteki job_request_id parametresiyle birlikte bir HTTPS GET çağrısı kullanılarak çağrılabilir.

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

Aşağıdaki gibi bir yanıt alırsınız. Bu yanıtta işin durumu ve hata mesajları gösterilir.

{
    "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ş/grup kimliğidir.
job_status Dize Bu, iş isteğinin durumudur.
request_received_at Dize İsteğin alındığı saat.
request_updated_at Dize İşin son güncellenme zamanı.
input_data_blob_prefix Dize Bu, createJob olarak ayarlanan giriş verisi ön ekidir.
input_data_bucket_name Dize Bu, toplanabilir raporların depolandığı reklam teknolojisinin giriş verileri grubudur. Bu alan createJob olarak ayarlandı.
output_data_blob_prefix Dize Bu, createJob olarak ayarlanan çıkış verisi ön ekidir.
output_data_bucket_name Dize Bu, reklam teknolojisinin çıkış verileri paketidir. Özet raporlar oluşturulduktan sonra burada depolanır. Bu alan createJob olarak ayarlandı.
request_processing_started_at Dize Son işleme denemesinin başlatıldığı zaman. Bu süre, iş kuyruğunda bekleme süresini içermez. (Toplam işleme süresi = request_updated_at - request_processing_started_at)
result_info Sözlük Bu, createJob ve iş hakkındaki tüm bilgilerin sonucudur. Bu işlemle return_code, return_message, finished_at ve error_summary gösterilir.
result_info.return_code Dize İş sonucunun döndürme kodu. Toplama Hizmeti'nde bir sorun ortaya çıktığında sorunun ne olabileceğini anlamak için bu bilgilere ihtiyaç duyulur.
result_info.return_message Dize İşin sonucu olarak döndürülen mesaj (başarılı veya başarısız). Bu bilgiler, toplama hizmeti hatalarının araştırılması sırasında da gerekli olacaktır.
result_info.error_summary Sözlük İş için döndürülen hatalar. Bu raporda, hangi tür hatalarla kaç raporun başarısız olduğu gösterilir.
result_info.finished_at Zaman damgası İşin tamamlandığı zaman damgası.
result_info.error_summary.error_counts Liste Bu işlem, 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ı, kategori, error_count, description içerir.
result_info.error_summary.error_messages Liste Bu komut, işlenemeyen raporların 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 birbirini dışlar. Bu, raporun alındığı raporlama URL'si veya raporlama kaynağı olacaktır. Kaynak, Toplama Hizmeti İlk Katılımı'nda kayıtlı olan sitenin bir parçasıdır. Bu değer, createJob isteğinde belirtilir.
job_parameters.reporting_site Dize attribution_report_to üyeliğine karşılıklı olarak özeldir. Bu, raporun alındığı raporlama URL'sinin veya raporlama kaynağının ana makine adı olacaktır. Kaynak, Toplama Hizmeti İlk Kayıt'ına kaydedilen sitenin bir parçası olacaktır. Tüm raporlama kaynaklarının bu parametrede belirtilen raporlama sitesine ait olması koşuluyla, aynı istekte birden fazla raporlama kaynağı olan raporlar gönderebileceğinizi unutmayın. Bu değer, createJob isteğinde belirtilir. Ayrıca, paketin yalnızca iş oluşturulurken birleştirmek istediğiniz raporları içerdiğinden emin olun. Bu giriş veri paketine, iş parametresinde belirtilen raporlama sitesiyle eşleşen raporlama kaynaklarıyla eklenen tüm raporlar işlenir. Örneğin, bir reklam teknolojisi https://exampleabc.com raporlama kaynağını kaydettiyse ancak giriş verileri paketine https://1.exampleabc.com, https://2.exampleabc.com ve https://3.examplexyz.com'ten raporlar eklerse. Yalnızca iş içinde kayıtlı raporlama kaynağıyla eşleşen pakete eklenen raporlar birleştirilir. Bu kaynak https://exampleabc.com olur.
job_parameters.debug_privacy_epsilon Kayan nokta, Çift İsteğe bağlı alandır. Hiçbiri geçmezse varsayılan değer 10'dur. 0-64 arasında bir değer kullanılabilir. Değer değişebilir. Bu değer, createJob isteğinde belirtilmiştir.
job_parameters.report_error_threshold_percentage Çift İsteğe bağlı alan. Bu, iş başarısız olmaya başlamadan önce başarısız olabilecek raporların yüzdesi eşiğidir. Boş bırakılırsa varsayılan değer %10'dur. Bu değer, createJob isteğinde belirtilir.
job_parameters.input_report_count Uzun değer İsteğe bağlı alan. Bu iş için giriş verisi olarak sağlanan toplam rapor sayısı. Bu değer, report_error_threshold_percentage ile birlikte raporlar hatalar nedeniyle hariç tutulduğunda işin erken başarısız olmasını sağlar. Bu değer, createJob isteğinde belirtilmiştir.
job_parameters.filtering_ids Dize İsteğe bağlı alandır. İmzasız filtreleme kimliklerinin virgülle ayrılmış listesi. Eşleşen filtreleme kimliği dışındaki tüm katkılar filtrelenir. Bu değer, createJob isteğinde belirtilmiştir. (ör. "filtering_ids":"12345,34455,12". Varsayılan değer "0"dır.)