דף זה תורגם על ידי Cloud Translation API.

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

במדריך למתחילים, תוכלו לקבל אסימון OAuth עבור החשבון שלכם, ולשלוח בקשות לנקודות הקצה של 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&
include_granted_scopes=true&
state=developer-specified-value
```
בכתובת ה-URL:
- client_id הוא מזהה הלקוח שלך ב-OAuth.
- redirect_uri הוא ה-URI המורשה להפניה אוטומטית. לדוגמה: https://google.com.
שימו לב שההיקף בכתובת ה-URL של המדריך למתחילים הוא היקף פעילות החיפוש. אפשר גם להשתמש בהיקף הפעילות ב-YouTube או בשני ההיקפים.
מדביקים את כתובת ה-URL בסרגל הכתובות של הדפדפן ופועלים לפי השלבים בתהליך OAuth. כדי לעשות את זה, נכנסים לחשבון שנמצא בבעלות או בשליטה של הארגון שלכם שבו אתם משתמשים במדריך למתחילים.

זהו החשבון שקיבל הסכמה להיקפי ההרשאות של OAuth. מסך ההסכמה אמור להיראות כך (הטקסט במסך עשוי להיות שונה מהטקסט בתמונה הזו):
אחרי שתביעו הסכמה, המערכת תעביר אתכם ל-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"
}

עליכם לאסוף את אסימון ה-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. מזהה המשימה משמש לאחזור המצב של ארכיון הנתונים.
```
{
  "archiveJobId": "<your_job_id>"
}
```
אם לא תספקו אסימון 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 המשרה. אם המשימה לא הושלמה, התשובה תציג את המצב הנוכחי. עליכם לשלוח בקשות לנקודת הקצה הזו מדי פעם עד שהמשימה תסתיים.
```
{
  "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": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

שולחים בקשה מאומתת לנקודת הקצה 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"
  }