از دسترسی مبتنی بر زمان استفاده کنید

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

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

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

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

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

پیش نیازها

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

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

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

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

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

یک URL مانند زیر بنویسید.
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
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 موافقت می کند. صفحه رضایت باید به این شکل باشد (متن موجود در صفحه شما ممکن است با متن این تصویر متفاوت باشد):
محدوده های دسترسی و مدت زمان اشتراک گذاری دسترسی به داده های حساب را انتخاب کنید (یک بار، 30 روز یا 180 روز). برای این شروع سریع، 30 روز را انتخاب کنید.
پس از اعطای رضایت و تصمیم گیری در مورد مدت زمان دسترسی، باید به URI تغییر مسیر هدایت شوید—https://google.com. نشانی اینترنتی که در نوار آدرس ایجاد می‌شود شامل یک کد مجوز است که در مرحله بعد با یک نشانه OAuth مبادله می‌کنید.
به عنوان مثال، اگر حساب کاربری به OAuth دسترسی به محدوده dataportability.myactivity.search اعطا کند، URL تولید شده به شکل زیر است:
```
https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
برای مبادله یک کد مجوز برای یک نشانه دسترسی، با نقطه پایانی oauth token تماس بگیرید:
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'
```
پاسخ باید به این صورت باشد:
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}
```
در URL، your_OAuth_token رشته ای است که نشان دهنده توکن است.
فیلد refresh_token_expires_in بر حسب ثانیه است و نشان می دهد که کاربر 30 روز (2592000 ثانیه) یا 180 روز (15552000 ثانیه) دسترسی را انتخاب کرده است. اگر برنامه شما وضعیت انتشار آزمایشی دارد، در عوض 7 روز (604800 ثانیه) بدون توجه به انتخاب کاربر، دسترسی دارید.
مهم: رمز دسترسی 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 برای فراخوانی نقاط پایانی 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 و 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.
```
در مرحله بعد، یک درخواست احراز هویت شده به نقطه پایانی 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"
}
```
اگر کار کامل شود، پاسخ شامل وضعیت و یک یا چند نشانی اینترنتی امضا شده است که برای دانلود بایگانی داده ها استفاده می شود.
```
{
  "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. 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}"
...

پس از 24 ساعت می‌توانید درخواست صادرات جدید کنید، اما ابتدا باید توکن تازه‌سازی خود را با یک توکن دسترسی تازه مبادله کنید.
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'
```
پاسخ باید به این صورت باشد:
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}
```
اگر کاربر دسترسی را تمدید کند، زمان انقضا جدید در قسمت refresh_token_expires_in منعکس می شود.
می توانید از نشانه دسترسی جدید برای تکرار مراحل InitiatePortabilityArchive و GetPortabilityArchiveState استفاده کنید.