שיטות של Call Data Portability API

ממשק ה-API להעברת נתונים מורכב מהשיטות הבאות:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive
  • archiveJobs.cancelPortabilityArchive
  • accessType.check

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 נקראת כדי לאחזר את המצב הנוכחי של משימה הייצוא של ארכיון הנתונים. כשמתקשרים למזהה getPortabilityArchiveState, צריך לציין את job_id: GetPortabilityArchiveState(job_id). צריך גם לספק אסימון OAuth עם היקפים שתואמים לקבוצות המשאבים שבהן נעשה שימוש בבקשה initiate.

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

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

resetAuthorization

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

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

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

archiveJobs.retryPortabilityArchive

השיטה archiveJobs.retryPortabilityArchive נקראת כדי לנסות שוב משימות שנכשלו, שבהן השיטה archiveJobs.getPortabilityArchiveState כבר החזירה מצב של FAILED. המצב הזה יכול לקרות בגלל כשל זמני בקצה העורפי. במקרה כזה, תוכלו לנסות שוב לייצא את הנתונים בלי לקבל מהמשתמש אסימון OAuth חדש. כשקוראים ל-retryPortabilityArchive, צריך לספק את job_id יחד עם אסימון OAuth תקף. לאחר מכן, נקודת הקצה תנסה ליצור ייצוא של אותם קבוצות משאבים שביקשת בבקשה הראשונית initiatePortabilityArchive. אם הפעולה תתבצע בהצלחה, נקודת הקצה הזו תחזיר 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).

archiveJobs.cancelPortabilityArchive

כשיש לכם גישה מתמשכת לנתוני משתמשים, אתם יכולים לבטל משימה מסוימת בלי לבטל את הטוקנים הקיימים באמצעות השיטה archiveJobs.cancelPortabilityArchive. אפשר להשתמש באפשרות הזו כשאין יותר צורך במשימה או במשאב, ואתם רוצים לאפס את המכסה של המשימה. כדי לבטל את המשימה, היא צריכה להיות מסוג IN_PROGRESS ונוצרה עם גישה מבוססת-זמן.

לדוגמה, אפשר לבטל משימה מבוססת-זמן שנמצאת בתהליך עבור myactivity.youtube ו-youtube.public_videos, ואז להתחיל משימה חדשה רק עבור myactivity.youtube.

accessType.check

השיטה accessType.check מאפשרת לבדוק אם אסימון OAuth מאשר גישה מבוססת-זמן או גישה חד-פעמית לפני שמתחילים את המשימה. לדוגמה, אם המשתמש מעניק גישה חד-פעמית, יכול להיות שתרצו לייצא את כל ההיסטוריה שלו. אם הוא מעניק גישה מבוססת-זמן, יכול להיות שתרצו לייצא רק את הנתונים מהיום האחרון.

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