שימוש בגישה מבוססת-זמן

במדריך למתחילים הזה תלמדו איך לקבל אסימון OAuth לחשבון שלכם ולשלוח בקשות חוזרות לנקודות הקצה של Data Portability API.

במדריך למתחילים הזה נסביר איך משתמשים ב-Data Portability API כדי לקבל גישה מבוססת-זמן לנתוני משתמשים. במאמר תחילת השימוש ב-Data Portability API מוסבר איך לקבל גישה חד-פעמית לנתוני משתמשים. במאמר החלת מסנני זמן מוסבר איך מחילים מסנני זמן על הבקשה.

מה תלמדו

במדריך למתחילים הזה תלמדו איך:

• שולחים בקשה מאומתת לנקודת הקצה InitiatePortabilityArchive על ידי מתן אסימון OAuth תקף. התגובה צריכה לכלול job_id תקין.
• שולחים בקשה מאומתת לנקודת הקצה GetPortabilityArchiveState. התגובה צריכה לכלול מצב עבודה תקין, וכשהמשימה תושלם, היא צריכה לכלול כתובת URL חתומה.
• שולחים בקשה מאומתת עם טוקן OAuth תקין לנקודת הקצה InitiatePortabilityArchive בפעם השנייה, באמצעות אותם פרטי כניסה. הפונקציה הזו מחזירה שגיאה מסוג FAILED_PRECONDITION אם הבקשה נשלחת תוך 24 שעות ממועד שליחת הבקשה הראשונית.

דרישות מוקדמות

כדי להריץ את המדריך למתחילים הזה, צריך:

• מוודאים ש-Data Portability API זמין למשתמשים במיקום שלכם. בשאלות הנפוצות שבדף 'שיתוף עותק של הנתונים שלכם עם צד שלישי' מפורטת רשימה של המדינות והאזורים הנתמכים.
• מבצעים את שלבי ההגדרה של Data Portability API.
• פועלים לפי השלבים להגדרת OAuth עבור אפליקציות אינטרנט בצד השרת.
  • כשיוצרים את פרטי הכניסה להרשאה, חשוב לכתוב בצד את מזהה הלקוח ב-OAuth 2.0, את הסוד של הלקוח ואת ה-URI המורשה להפניה אוטומטית (לדוגמה, https://google.com). תצטרכו אותם בהמשך המדריך למתחילים.
  • כשמגדירים היקפי הרשאות ל-Data Portability API, חשוב לזכור שבמדריך למתחילים הזה נעשה שימוש בקבוצת המשאבים myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
  • כשבוחרים את משך הזמן שרוצים לתת גישה, צריך לבחור באפשרות 30 ימים כדי לבדוק את הרשאת הגישה מבוססת-הזמן.
• מקבלים טוקן OAuth.
• לקבל גישה לחשבון שבבעלות הארגון או בשליטתו. נתוני הפעילות בחיפוש של החשבון הזה מיוצאים במדריך למתחילים הזה.

קבלת טוקן OAuth

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

כדי לקבל טוקן OAuth:

1. יוצרים כתובת URL כמו זו:

   https://accounts.google.com/o/oauth2/v2/auth?
   client_id=client_id&
   redirect_uri=redirect_uri&
   response_type=code&
   access_type=offline&
   scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
   state=developer-specified-value

   בכתובת ה-URL:

   • client_id הוא מזהה הלקוח ב-OAuth.
   • redirect_uri הוא מזהה ה-URI המורשה להפניה אוטומטית. לדוגמה: https://google.com.

   שימו לב שההיקף שמופיע בכתובת ה-URL של המדריך למתחילים הזה הוא היקף הפעילות בחיפוש. אפשר גם להשתמש בהיקף הפעילות ב-YouTube או בשני ההיקפים.

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

   זהו החשבון שמביע הסכמה להיקפי ההרשאות של OAuth. מסך ההסכמה אמור להיראות כך (הטקסט במסך עשוי להיות שונה מהטקסט בתמונה הזו):

   

3. בוחרים את ההיקפים של הגישה שרוצים להעניק ואת משך הזמן לשיתוף הגישה לנתונים של החשבון (פעם אחת, 30 ימים או 180 ימים). במדריך למתחילים הזה, בוחרים באפשרות 30 ימים.

4. אחרי מתן ההסכמה והגדרת משך הגישה, המערכת אמורה להפנות אתכם לכתובת ה-URI להפניה אוטומטית – https://google.com. כתובת ה-URL שנוצרת בסרגל הכתובות כוללת קוד הרשאה, שתחליפו באסימון OAuth בשלב הבא.

   לדוגמה, אם חשבון המשתמש מעניק ל-OAuth גישה להיקף dataportability.myactivity.search, כתובת ה-URL שנוצרת נראית כך:

   https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

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

   curl https://oauth2.googleapis.com/token\
   -H 'Content-Type: application/x-www-form-urlencoded' -X POST\
   -d 'code=your_auth_code&\
   redirect_uri=redirect_uri\
   client_id=client_id&\
   client_secret=client_secret&\
   grant_type=authorization_code'

   התגובה אמורה להיראות כך:

   {
     "access_token": your_OAuth_token,
     "expires_in": 3920,
     "token_type": "Bearer",
     "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
     "refresh_token": your_refresh_token,
     "refresh_token_expires_in": 2591999
   }

   בכתובת ה-URL, your_OAuth_token היא מחרוזת שמייצגת את האסימון.

   השדה refresh_token_expires_in הוא בשניות ומשקף את משך הגישה שבחר המשתמש: 30 יום (2,592,000 שניות) או 180 יום (1,555,2000 שניות). אם סטטוס הפרסום של האפליקציה הוא בדיקה, תהיה לכם גישה למשך 7 ימים (604,800 שניות) ללא קשר לבחירה של המשתמש.

6. כדי לאמת את אסימון ה-OAuth, מדביקים את כתובת ה-URL הזו בדפדפן:

   https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

   התגובה אמורה להיראות כך:

   {
     "azp": <your_azp_value>,
     "aud": <your_aud_value>,
     "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
     "exp": "1694210968",
     "expires_in": "3334",
     "access_type": "online"
   }
   

   אין צורך בשדות azp או aud כדי לשלוח בקשות. השדה azp מייצג את client_id של המגיש המורשה, והשדה aud מזהה את הקהל שאסימון זה מיועד לו, והוא יהיה שווה לאחד ממזהי הלקוח של האפליקציה.

7. אוספים את הטוקן של OAuth ואת מפתח ה-API. הם נדרשים כדי לבצע קריאות ל-Data Portability API.

שליחת בקשות לנקודות הקצה

במדריך למתחילים הזה נעשה שימוש בפקודות curl כדי לקרוא לנקודות הקצה של Data Portability API. כדי להשתמש בפקודות האלה, צריך את אסימון ה-OAuth ומפתח ה-API שאספתם קודם.

כדי לקרוא ל-Data Portability API:

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

   מריצים את פקודת ה-curl הבאה:

   curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{"resources":["myactivity.search"]}' \
   https://dataportability.googleapis.com/v1/portabilityArchive:initiate

   בפקודה:

   • your_OAuth_token הוא טוקן ה-OAuth שלכם.

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

   {
     "archiveJobId": "<your_job_id>"
     "accessType": "ACCESS_TYPE_TIME_BASED"
   }
   

   אם לא תספקו טוקן OAuth תקין, תופיע הודעת השגיאה הבאה:

   Request had invalid authentication credentials. Expected OAuth 2.0 access
   token, login cookie or other valid authentication credential. See
   https://developers.google.com/identity/sign-in/web/devconsole-project.

2. בשלב הבא, שולחים בקשה מאומתת לנקודת הקצה GetPortabilityArchiveState כדי לאחזר את הסטטוס של משימת הארכיון.

   מריצים את פקודת ה-curl הבאה:

   curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
   -H "Content-Type: application/json; charset=utf-8" \
   https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState

   בפקודה:

   • your_OAuth_token הוא טוקן ה-OAuth שלכם.
   • your_job_id הוא מזהה המשימה שהוחזר מהבקשה InitiatePortabilityArchive.

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

   {
     "state": "IN_PROGRESS"
   }
   

   אם המשימה הושלמה, התשובה תכלול את המצב וכתובת URL חתומה אחת או יותר שמשמשות להורדת ארכיון הנתונים.

   {
     "state": "COMPLETE",
     "urls": [
       "<signed_url>"
     ]
   }
   

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

   אם מופיע המצב FAILED בתגובה, אפשר לנסות שוב את הייצוא באמצעות השיטה RetryPortabilityArchive.

3. חוזרים על הפקודה הקודמת כדי לשלוח בקשה מאומתת לנקודת הקצה InitiatePortabilityArchive.

   curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{"resources":["myactivity.search"]}' \
   https://dataportability.googleapis.com/v1/portabilityArchive:initiate

   בפקודה:

   • your_OAuth_token הוא טוקן ה-OAuth שלכם.

   בתגובה אמורה להופיע הודעה על כך שכבר ייצאתם את המשאב myactivity.search, וגם חותמת זמן עם המועד שבו תוכלו לנסות שוב.

   ...
     "error": {
       "code": 429,
       "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
       "status": "RESOURCE_EXHAUSTED",
       "details": [
         {
           "@type": "type.googleapis.com/google.rpc.ErrorInfo",
           "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
           "domain": "dataportability.googleapis.com"
     "metadata": {
       "previous_job_ids": "#{previous_job_ids}"
       "access_type": "ACCESS_TYPE_TIME_BASED"
       "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
   ...
   

4. אחרי 24 שעות תוכלו לבקש ייצוא חדש, אבל קודם תצטרכו להחליף את אסימון הרענון באסימון גישה חדש.

   curl https://oauth2.googleapis.com/token\
   -H 'Content-Type: application/x-www-form-urlencoded' -X POST\
   -d 'refresh_token=your_refresh_token&\
   client_id=client_id&\
   client_secret=client_secret&\
   grant_type=refresh_token'

   התגובה אמורה להיראות כך:

   {
     "access_token": your_OAuth_token,
     "expires_in": 3920,
     "token_type": "Bearer",
     "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
     "refresh_token_expires_in": 2505599
   }

   אם המשתמש יחדש את הגישה, מועד התפוגה החדש יופיע בשדה refresh_token_expires_in.

   אפשר להשתמש באסימון הגישה החדש כדי לחזור על השלבים InitiatePortabilityArchive ו-GetPortabilityArchiveState.