فیلترهای زمان را برای درخواست های خود اعمال کنید

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

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

چیزی که یاد می گیرید

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

درخواست‌های احراز هویت مکرر را به نقطه پایانی InitiatePortabilityArchive ارسال کنید تا فقط داده‌های جدید را از آخرین صادرات خود صادر کنید.
یک درخواست احراز هویت شده به نقطه پایانی InitiatePortabilityArchive ارسال کنید تا فقط داده‌های ۶ ماه گذشته صادر شود.
یک درخواست احراز هویت شده به نقطه پایانی 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.
- وقتی مقدار زمانی را که می‌خواهید اجازه دسترسی را انتخاب کنید، باید 30 روز را برای آزمایش فیلتر کردن زمان با دسترسی مبتنی بر زمان انتخاب کنید. (فیلترهای زمانی با دسترسی یکباره نیز کار می کنند).
یک توکن 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 برای این شروع سریع، محدوده فعالیت جستجو است. می توانید از هر محدوده ای که از فیلترهای زمان پشتیبانی می کند استفاده کنید.
هشدار: دامنه‌های 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&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 برای فراخوانی نقاط پایانی API Portability Data با مُهرهای زمانی برای فیلتر کردن داده‌های صادر شده استفاده می‌کنید. این دستورات به نشانه OAuth و کلید API نیاز دارند که قبلاً جمع‌آوری کرده‌اید.

داده های آخرین صادرات

می‌توانید از فیلترهای زمان با دسترسی مبتنی بر زمان برای صادرات داده‌های جدید از آخرین صادرات خود استفاده کنید. به عنوان مثال، محدوده https://www.googleapis.com/auth/dataportability.myactivity.search را در نظر بگیرید.

ابتدا یک درخواست احراز هویت شده به نقطه پایانی 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 یک 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.
```
در مرحله بعد، یک درخواست احراز هویت شده به نقطه پایانی 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 دوباره امتحان کنید.
حداقل 24 ساعت صبر کنید و سپس با استفاده از همان دستور مرحله 1، درخواست دیگری برای InitiatePortabilityArchive بدهید، اما این بار از 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
```
توجه: می‌توانید start_time طوری تنظیم کنید که کمی با export_time همپوشانی داشته باشد تا اطمینان حاصل شود که داده‌های تولید شده در بین درخواست‌ها در صادرات گنجانده شده است.
برای دسترسی مبتنی بر زمان، این باز خواهد گشت:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
مرحله 2 را برای ارسال یک درخواست احراز هویت به نقطه پایانی GetPortabilityArchiveState برای بازیابی وضعیت کار بایگانی (با استفاده از <your_job_id_2> ) تکرار کنید.

هنگامی که کار کامل شد، پاسخ این خواهد بود:

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

بررسی کنید که داده‌های صادرات دوم فقط حاوی داده‌های جدیدی باشد که پس از صادرات اول ایجاد شده است.

داده های 6 ماه گذشته

همچنین می‌توانید از فیلترهای زمان استفاده کنید تا فقط جدیدترین داده‌ها را به جای مجموعه کامل صادر کنید.

فرض کنید تاریخ امروز 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"
}
```
برای بازیابی وضعیت کار بایگانی، از نقطه پایانی 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 مُهر زمانی است که در مرحله 1 تماس با InitiatePortabilityArchive برقرار شد.
بررسی کنید که صادرات فقط حاوی داده‌های شش ماه گذشته باشد.

داده های یک دوره زمانی خاص

می‌توانید از فیلترهای زمان برای صادرات داده‌ها از محدوده خاصی از تاریخ‌ها استفاده کنید، مانند داده‌های تنها از سال ۲۰۲۳.

ابتدا یک درخواست احراز هویت شده به نقطه پایانی 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"
}

برای بازیابی وضعیت کار بایگانی، از نقطه پایانی 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.
بررسی کنید که صادرات فقط حاوی داده‌های مربوط به سال 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 .