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

במדריך למתחילים הזה תלמדו איך לקבל אסימון 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 לאפליקציות אינטרנט ב-JavaScript. בסביבת הייצור, בדרך כלל משתמשים בתהליך אחר, כמו תהליך OAuth לאפליקציות שרת אינטרנט. כדי לפשט את התהליך, במדריך למתחילים הזה נעשה שימוש בתהליך של אפליקציית אינטרנט ב-JavaScript.
    • כשיוצרים את פרטי הכניסה להרשאה, חשוב לכתוב בצד את מזהה הלקוח ב-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. התהליך הזה מתבסס על התהליך לאפליקציות אינטרנט של JavaScript. התהליך הזה לא מחזיר אסימון רענון.

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

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

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

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
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&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

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

  5. כדי לאמת את אסימון ה-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 מזהה את הקהל שאסימון זה מיועד לו, והוא יהיה שווה לאחד ממזהי הלקוח של האפליקציה.

  6. אוספים את הטוקן של 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}"
...