החלת מסנני זמן על הבקשות

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

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

מה תלמדו

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

  • שולחים בקשות מאומתות חוזרות ונשנות לנקודת הקצה InitiatePortabilityArchive כדי לייצא רק נתונים חדשים מאז הייצוא האחרון.
  • שולחים בקשה מאומתת לנקודת הקצה InitiatePortabilityArchive כדי לייצא רק נתונים מ-6 החודשים האחרונים.
  • שולחים בקשה מאומתת לנקודת הקצה InitiatePortabilityArchive כדי לייצא רק נתונים מתקופה ספציפית.

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

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

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

  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 שאספתם קודם.

נתונים מהייצוא האחרון

אפשר להשתמש במסנני זמן עם גישה מבוססת-זמן כדי לייצא את הנתונים החדשים מאז הייצוא האחרון. לדוגמה, ההיקף https://www.googleapis.com/auth/dataportability.myactivity.search.

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

    {
  "archiveJobId": "<your_job_id_1>"
  "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_1/portabilityArchiveState

    בפקודה:

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

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

    {
  "state": "IN_PROGRESS"
}

    אם המשימה הושלמה, התשובה תכלול את המצב וכתובת URL חתומה אחת או יותר שמשמש להורדת ארכיון הנתונים. יש גם שדה export_time שמייצג את חותמת הזמן של הקריאה הראשונה ל-InitiatePortabilityArchive.

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

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

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

  3. ממתינים לפחות 24 שעות ושולחים בקשה נוספת ל-InitiatePortabilityArchive באמצעות אותה הפקודה כמו בשלב 1, אבל הפעם משתמשים ב-export_time כ-start_time.

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

    לגישה מבוססת-זמן, הפונקציה תחזיר:

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

  4. חוזרים על שלב 2 כדי לשלוח בקשה מאומתת לנקודת הקצה (endpoint) GetPortabilityArchiveState כדי לאחזר את הסטטוס של משימה הארכיון (באמצעות <your_job_id_2>).

  5. כשהמשימה תושלם, התשובה תהיה:

      {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

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

נתונים מ-6 החודשים האחרונים

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

  1. נניח שהתאריך של היום הוא 2024-10-01 ואתם רוצים לייצא את הנתונים של 6 החודשים האחרונים. קודם שולחים בקשה מאומתת לנקודת הקצה InitiatePortabilityArchive עם start_time של '2024-04-01T00:00:00Z'.

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

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

    לגישה מבוססת-זמן, הפונקציה תחזיר:

    {
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

  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/job_id_1/portabilityArchiveState

    כשהמשימה תושלם, התשובה תהיה:

    {
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}

    הערה: הערך של start_time הוא הערך של start_time שצוין בשלב 1, והערך של export_time הוא חותמת הזמן של הקריאה ל-InitiatePortabilityArchive שבוצעה בשלב 1.

  3. מוודאים שהייצוא מכיל רק נתונים מ-6 החודשים האחרונים.

נתונים מתקופת זמן ספציפית

אפשר להשתמש במסנני זמן כדי לייצא נתונים מטווח תאריכים ספציפי, למשל נתונים מ-2023 בלבד.

  1. קודם שולחים בקשה מאומתת לנקודת הקצה InitiatePortabilityArchive עם start_time של '2023-01-01T00:00:00Z' ו-end_time של '2023-12-31T23:59:59Z'.

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

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    לגישה מבוססת-זמן, הפונקציה תחזיר:

    {
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

  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/job_id_1/portabilityArchiveState

    כשהמשימה תושלם, התשובה תהיה:

    {
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

    שימו לב ש-start_time הוא start_time שצוין בשלב 1 ו-export_time שווה ל-end_time שצוין בשלב 1.

  3. מוודאים שהייצוא מכיל רק נתונים מ-2023.

היקפים נתמכים

ההיקפים הבאים תומכים במסנני זמן:

  • https://www.googleapis.com/auth/dataportability.myactivity.youtube
  • https://www.googleapis.com/auth/dataportability.myactivity.maps
  • https://www.googleapis.com/auth/dataportability.myactivity.search
  • https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
  • https://www.googleapis.com/auth/dataportability.myactivity.shopping
  • https://www.googleapis.com/auth/dataportability.myactivity.play
  • https://www.googleapis.com/auth/dataportability.chrome.history

זהירות: בקשות עם סינון לפי זמן שכוללות היקפים נתמכים ולא נתמכים יגרמו לשגיאה INVALID_ARGUMENT עם ההודעה The requested resources do not support time filters.