תחילת השימוש ב-Data Portability API

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

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

מה תלמדו

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

שולחים בקשה מאומתת לנקודת הקצה InitiatePortabilityArchive על ידי הצגת אסימון OAuth תקף. התגובה צריכה להכיל job_id תקין.
שולחים בקשה מאומתת לנקודת הקצה GetPortabilityArchiveState. התגובה צריכה לכלול מצב עבודה תקין, וכשהמשימה תושלם, היא צריכה לכלול כתובת URL חתומה.
(אופציונלי) שולחים בקשה מאומתת עם אסימון OAuth תקף לנקודת הקצה InitiatePortabilityArchive בפעם השנייה, באמצעות אותם פרטי כניסה. הפעולה הזו מחזירה את השגיאה RESOURCE_EXHAUSTED והיא נועדה להדגיש את החשיבות של נקודת הקצה ResetAuthorization.
שולחים בקשה מאומתת לנקודת הקצה ResetAuthorization. הבקשה הזו מבטלת את כל היקפי ה-OAuth שהמשתמשים העניקו.
(אופציונלי) שולחים בקשה לנקודת הקצה InitiatePortabilityArchive באמצעות אותו אסימון OAuth שבו השתמשתם בעבר. הבקשה אמורה להיכשל אחרי איפוס ההרשאה.

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

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

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

קבלת טוקן OAuth

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

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

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

יוצרים כתובת 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 או בשני ההיקפים.

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

זהו החשבון שמביע הסכמה להיקפי ההרשאות של OAuth. מסך ההסכמה אמור להיראות כך (הטקסט במסך עשוי להיות שונה מהטקסט בתמונה הזו):
בוחרים את ההיקפים של הגישה שרוצים להעניק ואת משך הזמן לשיתוף הגישה לנתונים של החשבון (פעם אחת, 30 ימים או 180 ימים). במדריך למתחילים הזה, בוחרים באפשרות Only once.
אחרי מתן ההסכמה ובחירת משך הגישה, המערכת אמורה להפנות אתכם לכתובת ה-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 היא מחרוזת שמייצגת את האסימון.

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

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

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

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

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

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

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

(אופציונלי) חוזרים על הפקודה הקודמת כדי לשלוח בקשה מאומתת לנקודת הקצה 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. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

שולחים בקשה מאומתת לנקודת הקצה ResetAuthorization. הבקשה הזו מבטלת את כל היקפי הרשאות ה-OAuth שהוקצו על ידי משתמשים, ומאפשרת להפעיל את InitiatePortabilityArchive עבור קבוצת משאבים שכבר השתמשתם בה.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
בפקודה:
- your_OAuth_token הוא טוקן ה-OAuth שלכם.
הפקודה הזו מחזירה תגובה ריקה.

(אופציונלי) אחרי איפוס ההרשאה, שולחים בקשה נוספת לנקודת הקצה 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 שלכם.

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

...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }