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

פריסה וניהול של בקשות באמצעות שירות צבירה

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

סקירה כללית על Aggregation Service API — **איור 1.**סקירה כללית של Aggregation Service API

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

יצירת משימה

כדי ליצור משימה, שולחים בקשת POST לנקודת הקצה createJob. bash 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>"
  }
}

אם יצירת המשימה הושלמה, תקבלו קוד סטטוס HTTP‏ 202.

שימו לב: השדות 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`	מחרוזת	זהו נתיב הקטגוריה. בקובצי בודדים, אפשר להשתמש בנתיב. אם רוצים לבחור כמה קבצים, אפשר להשתמש בקידומת במסלול. דוגמה: התיקייה/הקובץ אוספים את כל הדוחות מהתיקייה 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 של הדיווח או המקור של הדיווח שבו התקבל הדוח. מקור האתר רשום בתהליך ההצטרפות ל-Aggregation Service.
`job_parameters.reporting_site`	מחרוזת	הערך הזה בלעדי לערך `attribution_report_to`. זהו שם המארח של כתובת ה-URL לדיווח או של מקור הדיווח שבו התקבל הדוח. מקור האתר רשום בתהליך ההצטרפות ל-Aggregation Service. הערה: אפשר לשלוח כמה דוחות עם מקורות שונים בבקשה אחת, בתנאי שכל המקורות שייכים לאותו אתר דיווח שצוין בפרמטר הזה.
`job_parameters.debug_privacy_epsilon`	נקודה צפה, Double	שדה אופציונלי. אם לא מועבר ערך, ערך ברירת המחדל הוא 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"`. החל מגרסה 2.10.0, הפעלות ניפוי באגים לא צורכות מתקציב הפרטיות.

קבלת עבודה

כשטכנולוגיית הפרסום רוצה לדעת מה הסטטוס של קבוצה שהתבקשה, היא יכולה לבצע קריאה לנקודת הקצה 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://exampleabc.com נכללים, גם אם הקטגוריה מכילה דוחות מתת-דומיינים (`https://1.exampleabc.com` וכו') או מדומיינים שונים לגמרי (`https://3.examplexyz.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').