این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

استفاده از Data Portability API را شروع کنید

در این شروع سریع، یک نشانه OAuth برای حساب خود دریافت می کنید و درخواست هایی را به نقاط پایانی Data Portability API ارسال می کنید.

آنچه یاد می گیرید

در این شروع سریع یاد می گیرید که چگونه:

با ارائه یک نشانه OAuth معتبر، یک درخواست احراز هویت را به نقطه پایانی InitiatePortabilityArchive ارسال کنید. پاسخ باید دارای یک job_id معتبر باشد.
یک درخواست احراز هویت شده به نقطه پایانی GetPortabilityArchiveState ارسال کنید. پاسخ باید شامل یک وضعیت شغلی معتبر و پس از تکمیل کار، یک URL امضا شده باشد.
(اختیاری) یک درخواست احراز هویت شده با یک نشانه OAuth معتبر برای بار دوم با استفاده از همان اعتبارنامه به نقطه پایانی InitiatePortabilityArchive ارسال کنید. این یک خطای RESOURCE_EXHAUSTED را برمی گرداند و در نظر گرفته شده است که اهمیت نقطه پایانی ResetAuthorization را برجسته کند.
یک درخواست احراز هویت شده به نقطه پایانی ResetAuthorization ارسال کنید. این درخواست همه دامنه های OAuth اعطایی شده توسط کاربر را لغو می کند.
(اختیاری) با استفاده از همان نشانه OAuth که قبلا استفاده می کردید، درخواستی را به نقطه پایانی InitiatePortabilityArchive ارسال کنید. پس از تنظیم مجدد مجوز، درخواست باید با شکست مواجه شود.

پیش نیازها

برای اجرای این شروع سریع، باید:

بررسی کنید که Data Portability API برای کاربران مکان شما در دسترس است. برای فهرستی از کشورها و مناطق پشتیبانی شده، به سوالات متداول در صفحه "به اشتراک گذاری یک نسخه از داده های خود با شخص ثالث" مراجعه کنید.
مراحل راه اندازی Data Portability API را کامل کنید.
مراحل را برای پیکربندی OAuth برای برنامه های وب جاوا اسکریپت دنبال کنید. در تولید، شما معمولاً از یک جریان متفاوت مانند جریان OAuth برای برنامه های کاربردی وب سرور استفاده می کنید. برای سادگی، این شروع سریع از جریان برنامه وب جاوا اسکریپت استفاده می کند.
- هنگامی که اعتبارنامه مجوز خود را ایجاد می کنید، شناسه مشتری OAuth 2.0 و URI تغییر مسیر مجاز خود را یادداشت کنید (به عنوان مثال، https://google.com). بعداً در شروع سریع به آنها نیاز خواهید داشت.
- وقتی دامنه‌ها را برای API انتقال داده پیکربندی می‌کنید ، توجه داشته باشید که این شروع سریع از گروه منبع myactivity.search استفاده می‌کند: https://www.googleapis.com/auth/dataportability.myactivity.search.
یک توکن OAuth دریافت کنید.
به یک حساب متعلق به یا تحت کنترل سازمان خود دسترسی پیدا کنید. داده‌های فعالیت جستجوی این حساب در این شروع سریع صادر می‌شود.

یک توکن OAuth دریافت کنید

برای این شروع سریع، یک درخواست مجوز برای دریافت یک نشانه OAuth با استفاده از یک URL ارسال می کنید. این فرآیند از جریان برنامه های وب جاوا اسکریپت استفاده می کند. این جریان نشانه تازه‌سازی را بر نمی‌گرداند.

برای یک برنامه تولیدی، شما معمولاً از یک جریان 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 یا هر دو دامنه استفاده کنید.
هشدار: دامنه های API Portability Data را با سایر انواع دامنه ها مخلوط نکنید یا محدوده های قبلاً اعطا شده را وارد نکنید زیرا این کار منجر به خطا می شود. برای جزئیات، محدودیت‌های محدوده را ببینید.
URL را در نوار آدرس مرورگر خود قرار دهید و مراحل موجود در جریان OAuth را دنبال کنید. این جریان از شما می‌خواهد که وارد حسابی شوید که متعلق به یا تحت کنترل سازمانتان است و برای این شروع سریع از آن استفاده می‌کنید.
این حسابی است که با محدوده های OAuth موافقت می کند. صفحه رضایت باید به این شکل باشد (متن موجود در صفحه شما ممکن است با متن این تصویر متفاوت باشد):
پس از اعطای رضایت، باید به URI تغییر مسیر هدایت شوید— https://google.com. نشانی اینترنتی که در نوار آدرس ایجاد می‌شود شامل نشانه دسترسی 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 برای فراخوانی نقاط پایانی API Portability Data استفاده می کنید. این دستورات به نشانه 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": "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"
  }