שיטות של Call Data Portability API

ה-Data Portability API מורכב מהשיטות הבאות:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive

portabilityArchive.initiate

מפעילים את השיטה portabilityArchive.initiate כדי להתחיל משימה חדשה של ייצוא נתונים.

כשמפעילים משימת ייצוא כדי ליצור ארכיון נתונים, צריך לבקש את קבוצת המשאבים המתאימה ולספק אסימון OAuth עם ההיקפים הנדרשים לאותה קבוצת משאבים. אסימון OAuth משמש לאישור הבקשה ולקביעה אילו נתוני משתמש מיוצאים.

לרשימה של כל קבוצות המשאבים שנתמכות על ידי שירות מסוים, תוכלו לעיין בדף העזר לסכימה של אותו שירות.

לדוגמה, אם אתם מייצאים נתונים של פעילות חיפוש, עליכם לקרוא לפונקציה InitiatePortabilityArchive(resources = ["myactivity.search"]). לבקשה חייב להיות מצורף אסימון OAuth עם היקף ההרשאות של OAuth: https://www.googleapis.com/auth/dataportability.myactivity.search.

למרות שאפשר לכלול כמה קבוצות משאבים בהפעלת InitiatePortabilityArchive אחת, לא מומלץ לעשות זאת. אפשר להאיץ את העיבוד על ידי יצירת בקשות InitiatePortabilityArchive נפרדות לכל קבוצת משאבים. שימו לב שכאשר מבקשים מספר קבוצות משאבים, לאסימון ה-OAuth המצורף צריך להיות מצורפים כל היקפי ההרשאות המתאימים.

לדוגמה, במקום לקרוא לפונקציה InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) על מנת ליצור ארכיון נתונים גם עבור פעילות בחיפוש וגם עבור פעילות ב-YouTube, בצע את הקריאות הנפרדות הבאות: InitiatePortabilityArchive(resources = ["myactivity.search"]) ו-InitiatePortabilityArchive(resources = ["myactivity.youtube"]).

הבקשה InitiatePortabilityArchive מחזירה job_id. מזהה המשימה הזה משמש לאחזור המצב של ארכיון הנתונים.

archiveJobs.getPortabilityArchiveState

השיטה archiveJobs.getPortabilityArchiveState נקראת כדי לאחזר את הstate הנוכחי של משימת הייצוא של ארכיון הנתונים. כשמבצעים קריאה ל-getPortabilityArchiveState, צריך לספק את job_id: GetPortabilityArchiveState(job_id). צריך גם לספק אסימון OAuth עם היקפים שתואמים לקבוצות המשאבים שבהן נעשה שימוש בבקשה initiate.

אם המצב הוא COMPLETE, מוחזרות כתובות URL חתומות של Cloud Storage שבהן אפשר להשתמש כדי להוריד את הנתונים. התוקף של כתובות ה-URL החתומות פג אחרי שש שעות, והנתונים זמינים למשך 14 ימים.

הטיפול בבקשת ארכיון עשוי להימשך כמה דקות, כמה שעות או אפילו כמה ימים, בהתאם לנפח הנתונים. תוכלו לבדוק את מצב הארכיון מדי 5 עד 60 דקות.

resetAuthorization

השיטה resetAuthorization מבצעת את הפעולות הבאות:

  • ביטול כל היקפי ההרשאות של OAuth שניתנו על ידי המשתמשים
  • ההרשאה הזו מאפשרת לאפליקציה לקרוא ל-InitiatePortabilityArchive לקבוצת משאבים שהשתמשת בה בעבר
  • הסרת הגישה לארכיוני נתונים קודמים

כשמבצעים קריאה ל-resetAuthorization, צריך לצרף אסימון OAuth בשביל המשתמש שאת ההרשאה שלו רוצים לאפס.

archiveJobs.retryPortabilityArchive

השיטה archiveJobs.retryPortabilityArchive נקראת כדי לנסות שוב משימות שנכשלו כאשר השיטה archiveJobs.getPortabilityArchiveState כבר החזירה state של FAILED. יכול להיות שהסיבה לכך היא כשל זמני בקצה העורפי. במקרה כזה, אפשר לנסות לייצא שוב בלי לקבל אסימון OAuth חדש מהמשתמש. כשמבצעים קריאה ל-retryPortabilityArchive, צריך לספק את job_id יחד עם אסימון OAuth תקף. לאחר מכן, נקודת הקצה תנסה ליצור ייצוא לאותן קבוצות משאבים שביקשת בבקשה הראשונית ל-initiatePortabilityArchive. אם הפעולה בוצעה בהצלחה, נקודת הקצה (endpoint) הזו מחזירה חדש job_id שאפשר להשתמש בו בקריאות אל getPortabilityArchiveState. אפשר לנסות שוב לבצע משימה שנכשלה עד שלוש פעמים.

למשל:

  1. מתקשרים אל InitiatePortabilityArchive(resources = ["myactivity.search"]) ומקבלים job_id: 0.

  2. אחרי חיוג אל GetPortabilityArchiveState(0), מקבלים JobSate: FAILED.

  3. לאחר מכן אפשר להתקשר אל RetryPortabilityArchive(0) כדי לקבל job_id: 1 במחיר של resources = ["myactivity.search"].

  4. לאחר מכן אפשר יהיה להמשיך להתקשר למספר GetPortabilityArchiveState(1).