דף זה תורגם על ידי Cloud Translation API.

הסבר על Aggregation Service API

אחרי הפריסה, שירות האגרגציה יחשוף שני נקודות קצה לשימוש בטכנולוגיות פרסום: createJob ו-getJob.

תרשים AgS

מידע נוסף על נקודות הקצה createJob ו-getJob זמין במסמכי התיעוד של Aggregation Service API.

createJob

קוראים לנקודת הקצה createJob באמצעות בקשת POST ב-HTTP, וצריך להוסיף לה גוף בקשה. אחרי ששולחים את הבקשה createJob, מקבלים תגובה מוצלחת מסוג HTTP 202.

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

דוגמה לגוף הבקשה של 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>"
  }
}

הערה: reporting_site ו-attribution_report_to הם בלעדיים באופן הדדי ורק נדרש אחד.

אפשר גם לבקש משימה לניפוי באגים על ידי הוספת debug_run ל-job_parameters. כדי להבין את מצב ניפוי הבאגים, כדאי לעיין במסמכי העזרה בנושא הפעלת ניפוי באגים של צבירה.

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

שדות בקשה

פרמטר	סוג	תיאור
`job_request_id`	מחרוזת	זהו מזהה ייחודי שנוצר על ידי טכנולוגיית הפרסום, והוא צריך להיות מורכב מאותיות ASCII באורך 128 תווים או פחות. הפעולה הזו מזהה את הבקשה של המשימה באצווה ומתייחסת לכל דוחות Avro המצטברים שצוינו ב-'input_data_blob_prefix' מקטגוריית הקלט שצוינה ב-input_data_bucket_name שמתארחים באחסון בענן של טכנולוגיית הפרסום. תווים: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
`input_data_blob_prefix`	מחרוזת	זהו הנתיב בקטגוריה. בקובצי בודדים, אפשר להשתמש בנתיב. אם מדובר בכמה קבצים, אפשר להשתמש בקידומת במסלול. דוגמה: התיקייה/file תאסוף את כל הדוחות מ-folder/file1.avro, מ-folder/file/file1.avro, מ-folder/file1/test/file2.avro.
`input_data_bucket_name`	מחרוזת	זוהי קטגוריית האחסון של נתוני הקלט או הדוחות שאפשר לצבור. נמצא באחסון בענן של טכנולוגיית הפרסום.
`output_data_blob_prefix`	מחרוזת	זהו נתיב הפלט בקטגוריה. יש תמיכה בקובץ פלט יחיד.
`output_data_bucket_name`	מחרוזת	זוהי קטגוריית האחסון שאליה יישלחו ה-`output_data`. הנתונים האלה נשמרים באחסון בענן של חברת טכנולוגיית הפרסום.
`job_parameters`	מילון	שדה חובה השדה הזה יכיל את השדות השונים כמו: `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`	מחרוזת	בדומה ל-`input_data_blob_prefix`, זה יהיה הנתיב ב-`output_domain_bucket_name` שבו יופיע קובץ ה-AVRO של דומיין הפלט. אם יש לכם כמה קבצים, תוכלו להשתמש בקידומת של הנתיב. אחרי ששירות האגרגציה משלימה את האצווה, דוח הסיכום נוצר וממוקם בקטגוריית הפלט `output_data_bucket_name` עם השם `output_data_blob_prefix`.
`job_parameters.output_domain_bucket_name`	מחרוזת	זהו הקטגוריה של האחסון של קובץ ה-AVRO של דומיין הפלט. נמצא באחסון בענן של טכנולוגיית הפרסום.
`job_parameters.attribution_report_to`	מחרוזת	בלעדי באופן הדדי ל-Reporting_site. זו תהיה כתובת ה-URL לדיווח או המקור לדיווח שבו התקבל הדוח. המקור יהיה חלק מהאתר הרשום בהצטרפות לשירות הצבירה.
`job_parameters.reporting_site`	מחרוזת	הערך הזה בלעדי לערך `attribution_report_to`. זה יהיה שם המארח של כתובת ה-URL לדיווח או של מקור הדיווח שבו התקבל הדוח. המקור יהיה חלק מהאתר שמופיע בטופס ההצטרפות לשירות האגרגציה. הערה: אפשר לשלוח דוחות עם כמה מקורות דיווח באותה בקשה, כל עוד כל מקורות הדיווח שייכים לאותו אתר המדווח שהוזכר בפרמטר הזה.
`job_parameters.debug_privacy_epsilon`	נקודה צפה, כפולה	שדה אופציונלי. אם לא עברו אף אחד, ברירת המחדל היא 10. אפשר להשתמש בערכים בין 0 ל-64. הערך יכול להיות שונה.
`job_parameters.report_error_threshold_percentage`	כפול	שדה אופציונלי. זהו הסף של אחוז הדוחות שיכולים להיכשל לפני שהמשימה תתחיל להיכשל. אם השדה הזה יישאר ריק, ברירת המחדל תהיה 10%.
`job_parameters.input_report_count`	ערך Long	שדה אופציונלי. המספר הכולל של הדוחות שסופקו כנתוני קלט למשימה הזו. הערך הזה, בשילוב עם `report_error_threshold_percentage`, יאפשר כשל מוקדם של המשימה כשדוחות מוחרגים בגלל שגיאות.
`job_parameters.filtering_ids`	מחרוזת	שדה אופציונלי. רשימה של מזהי סינון לא חתומים שמופרדים בפסיקים. כל התרומות שאינן תואמות למזהה הסינון יסוננו. לדוגמה,`"filtering_ids": "12345,34455,12"`. ערך ברירת המחדל הוא '0'.
`job_parameters.debug_run`	בוליאני	שדה אופציונלי. כשמריצים תוצאות ניפוי באגים, מתווספים הערות ודוחות סיכום של ניפוי באגים עם רעש וללא רעש כדי לציין אילו מפתחות נמצאים בקלט או בדוחות של הדומיין. בנוסף, לא מתבצעת אכיפה של קבצים כפולים בין קבוצות. חשוב לזכור שהפעלת ניפוי הבאגים מתייחסת רק לדוחות עם הדגל `"debug_mode": "enabled"`, והפעלות ניפוי הבאגים צורכות את התקציב.

getJob

כשספק טכנולוגיית הפרסום רוצה לדעת מה הסטטוס של קבוצה של בקשות שנשלחו, הוא יכול לקרוא לנקודת הקצה getJob. אפשר להפעיל את נקודת הקצה getJob באמצעות קריאת GET ב-HTTPS, יחד עם הפרמטר job_request_id בבקשה.

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

אמורה להופיע תגובה כמו זו. התגובה תכלול את סטטוס המשימה והודעות שגיאה.

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

שדות התגובה

פרמטר	סוג	תיאור
`job_request_id`	מחרוזת	זוהי המשימה הייחודית / מזהה האצווה שצוינו בבקשה של `createJob`.
`job_status`	מחרוזת	זהו הסטטוס של בקשת העבודה.
`request_received_at`	מחרוזת	המועד שבו הבקשה התקבלה.
`request_updated_at`	מחרוזת	השעה שבה המשימה עודכנה לאחרונה.
`input_data_blob_prefix`	מחרוזת	זוהי הקידומת של נתוני הקלט שהוגדרה ב-`createJob`.
`input_data_bucket_name`	מחרוזת	קטגוריית נתוני הקלט של טכנולוגיית הפרסום שבה נשמרים הדוחות שאפשר לצבור. השדה הזה מוגדר כ-`createJob`.
`output_data_blob_prefix`	מחרוזת	זוהי הקידומת של נתוני הפלט שהוגדרה ב-`createJob`.
`output_data_bucket_name`	מחרוזת	זוהי קטגוריית נתוני הפלט של טכנולוגיית הפרסום, שבה יישמרו דוחות הסיכום לאחר היצירה שלהם. השדה הזה מוגדר כ-`createJob`.
`request_processing_started_at`	מחרוזת	השעה שבה התחיל ניסיון העיבוד האחרון. הפעולה הזו לא כוללת את זמן ההמתנה בתור. (זמן העיבוד הכולל = `request_updated_at` - `request_processing_started_at`)
`result_info`	מילון	זו התוצאה של `createJob` וכל המידע שזמין לגבי העבודה. יוצגו `return_code`,‏ `return_message`,‏ `finished_at` ו-`error_summary`.
`result_info.return_code`	מחרוזת	קוד ההחזרה של תוצאת המשימה. אנחנו זקוקים למידע הזה כשמתרחשת בעיה בשירות הצבירה כדי להבין מה יכולה להיות הבעיה.
`result_info.return_message`	מחרוזת	ההודעה (הצלחה או כשל) שתוחזר כתוצאה מהמשימה. המידע הזה יידרש גם במהלך בדיקת כשלים בשירות הצבירה.
`result_info.error_summary`	מילון	השגיאות שמוחזרות לגבי המשימה. העמודה הזו תכלול את מספר הדוחות שנכשלו עם סוג השגיאה.
`result_info.finished_at`	חותמת זמן	חותמת הזמן של מועד סיום המשימה.
`result_info.error_summary.error_counts`	רשימה	הפקודה הזו תחזיר רשימה של הודעות השגיאה ומספר הדיווחים שנכשלו עם אותה הודעת שגיאה. כל ספירת שגיאות תכיל את הקטגוריה `error_count`, `description`.
`result_info.error_summary.error_messages`	רשימה	פעולה זו תחזיר רשימה של הודעות השגיאה לגבי דוחות שהעיבוד שלהם נכשל.
`job_parameters`	מילון	השדה הזה מכיל את הפרמטרים של המשימה שצוינו בבקשת `createJob`. מאפיינים רלוונטיים כמו 'output_domain_blob_prefix' ו-'output_domain_bucket_name'.
`job_parameters.attribution_report_to`	מחרוזת	הערך הזה בלעדי לערך `reporting_site`. זו תהיה כתובת ה-URL של הדיווח או מקור הדיווח שבו התקבל הדוח. המקור יהיה חלק מהאתר הרשום בהצטרפות לשירות הצבירה. זה מצוין בבקשה `createJob`.
`job_parameters.reporting_site`	מחרוזת	הערך הזה בלעדי לערך `attribution_report_to`. זה יהיה שם המארח של כתובת ה-URL לדיווח או של מקור הדיווח שבו התקבל הדוח. המקור יהיה חלק מהאתר הרשום בהצטרפות לשירות הצבירה. חשוב לשים לב: אתם יכולים לשלוח דוחות מכמה מקורות דיווח באותה בקשה, כל עוד כל מקורות הדיווח שייכים לאותו אתר דיווח שהוזכר בפרמטר הזה. הפרטים האלה מצוינים בבקשה `createJob`. בנוסף, חשוב לוודא שהקטגוריה מכילה רק את הדוחות שרוצים לצבור בזמן יצירת המשימה. כל הדוחות שיתווספו לקטגוריית נתוני הקלט הזו עם מקורות דיווח שתואמים לאתר הדיווח שצוין בפרמטר של המשימה יעברו עיבוד. לדוגמה, אם חברת טכנולוגיית פרסום רשמה מקור דיווח `https://exampleabc.com`, אבל בקטגוריה של נתוני הקלט היא מוסיפה דוחות מ-`https://1.exampleabc.com`, מ-`https://2.exampleabc.com` ומ-`https://3.examplexyz.com`. רק דוחות שנוספו לקטגוריה שתואמים למקור הדיווח הרשום במשימה יופיעו במצטבר, והוא יהיה `https://exampleabc.com`.
`job_parameters.debug_privacy_epsilon`	נקודה צפה, Double	שדה אופציונלי. אם לא עברו אף אחד, ברירת המחדל היא 10. אפשר להשתמש בערכים בין 0 ל-64. הערך יכול להיות שונה. זה מצוין בבקשה `createJob`.
`job_parameters.report_error_threshold_percentage`	כפול	שדה אופציונלי. זהו הסף של אחוז הדוחות שיכולים להיכשל לפני שהמשימה תתחיל להיכשל. אם השדה יישאר ריק, ערך ברירת המחדל הוא 10%. זה מצוין בבקשה `createJob`.
`job_parameters.input_report_count`	ערך Long	שדה אופציונלי. המספר הכולל של דוחות שסופקו כנתוני קלט למשרה הזו. הערך הזה, בשילוב עם `report_error_threshold_percentage`, יאפשר כשל מוקדם של המשימה כשדוחות מוחרגים בגלל שגיאות. זה מצוין בבקשה `createJob`.
`job_parameters.filtering_ids`	מחרוזת	שדה אופציונלי. רשימה של מזהי סינון לא חתומים שמופרדים בפסיקים. המערכת תסנן את כל התכנים שנוספו מלבד מזהה הסינון התואם. זה מצוין בבקשה `createJob`. (למשל, `"filtering_ids":"12345,34455,12"`. ערך ברירת המחדל הוא '0').