يتم طرح ميزات Data Portability API الجديدة الآن وستصبح متاحة للجميع بحلول 20 شباط (فبراير) 2025.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تطبيق فلاتر الوقت على طلباتك

في هذا الدليل السريع، ستحصل على رمز مميّز لبروتوكول OAuth لحسابك، وسترسل طلبات إلى نقاط نهاية Data Portability API باستخدام الطوابع الزمنية لفلترة data المصدَّرة.

يتناول دليل البدء السريع هذا كيفية استخدام واجهة برمجة التطبيقات Data Portability API مع الوصول المستنِد إلى الوقت وتطبيق فلاتر الوقت على الموارد المتوافقة. لمزيد من التفاصيل حول الوصول بالاستناد إلى الوقت إلى بيانات المستخدمين، اطّلِع على استخدام ميزة "الوصول بالاستناد إلى الوقت".

ما ستتعرّف عليه

في دليل بدء الاستخدام السريع هذا، ستتعرّف على كيفية:

أرسِل طلبات مُعتمَدة متكررة إلى نقطة نهاية InitiatePortabilityArchive لتصدير البيانات الجديدة فقط منذ آخر عملية تصدير.
أرسِل طلبًا مصادقًا عليه إلى نقطة النهاية InitiatePortabilityArchive لتصدير البيانات من آخر 6 أشهر فقط.
أرسِل طلبًا تمّت مصادقته إلى نقطة النهاية InitiatePortabilityArchive لتصدير البيانات من فترة زمنية محدّدة فقط.

المتطلبات الأساسية

لتنفيذ هذه الخطوات السريعة، عليك تنفيذ ما يلي:

تأكَّد من توفّر واجهة برمجة التطبيقات Data Portability API للمستخدمين في موقعك الجغرافي. للحصول على قائمة بالبلدان والمناطق التي تتوفّر فيها هذه الميزة، يُرجى الاطّلاع على الأسئلة الشائعة في صفحة "مشاركة نسخة من بياناتك مع جهة خارجية".
أكمِل خطوات الإعداد لواجهة Data Portability API.
اتّبِع الخطوات لضبط بروتوكول OAuth في تطبيقات الويب المستندة إلى JavaScript. في مرحلة الإنتاج، يتم عادةً استخدام مسار مختلف، مثل مسار OAuth لتطبيقات خادم الويب. من أجل البساطة، يستخدم دليل البدء السريع هذا مسار تطبيق الويب JavaScript.
- عند إنشاء بيانات اعتماد التفويض، دوِّن معرِّف عميل OAuth 2.0 وعنوان URL المُفوَّض لإعادة التوجيه (على سبيل المثال، https://google.com). ستحتاج إليها لاحقًا في الخطوة الأولى من البدء السريع.
- عند ضبط النطاقات لواجهة برمجة التطبيقات Data Portability API، يُرجى ملاحظة أنّ دليل البدء السريع هذا يستخدم مجموعة الموارد myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
- عند اختيار المدة التي تريد السماح بالوصول خلالها، عليك اختيار 30 يومًا لاختبار الفلترة حسب الوقت باستخدام إذن الوصول المستند إلى الوقت. (تعمل فلاتر الوقت أيضًا مع إذن الوصول لمرة واحدة).
الحصول على رمز 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 الخاص بدليل بدء الاستخدام السريع هذا هو نطاق نشاط البحث. يمكنك استخدام أي نطاقات تتيح استخدام "فلاتر الوقت".

تحذير: لا تُجمِّع بين نطاقات Data Portability API وأنواع أخرى من النطاقات، ولا تستخدِم عددًا كبيرًا جدًا من النطاقات في الوقت نفسه، ولا تُدرِج نطاقات تم منحها سابقًا لأنّ ذلك يؤدي إلى حدوث أخطاء. لمعرفة التفاصيل، يُرجى الاطّلاع على قيود النطاق.
الصِق عنوان URL في شريط العناوين في المتصفّح واتّبِع الخطوات الواردة في خطوات ملف تعريف الارتباط المتوافق مع أمان طبقة النقل (OAuth). تتطلّب هذه العملية تسجيل الدخول إلى الحساب الذي تملكه مؤسستك أو تتحكم فيه والذي تستخدمه في هذه الخطوة السريعة.

هذا هو الحساب الذي يوافق على نطاقات OAuth. من المفترض أن تظهر شاشة الموافقة على النحو التالي (قد يختلف النص في شاشتك عن النص في هذه الصورة):
اختَر النطاقات التي تريد منح إذن الوصول إليها ومدّة مشاركة إذن الوصول إلى بيانات الحساب (مرة واحدة أو 30 يومًا أو 180 يومًا). في هذه الخطوة السريعة، اختَر 30 يومًا. (تعمل فلاتر الوقت أيضًا مع إذن الولوج لمرة واحدة).
بعد منح الموافقة وتحديد مدة الوصول، من المفترض أن تتم إعادة توجيهك إلى عنوان URL لإعادة التوجيه: 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 المميّز ومفتاح واجهة برمجة التطبيقات. ستحتاج إلى هذه العناصر لإجراء اتصالات بواجهة برمجة التطبيقات Data Portability API.

إرسال الطلبات إلى نقاط النهاية

في هذا الدليل السريع، ستستخدم أوامر curl للاتّصال بنُقط نهاية Data Portability API باستخدام علامات زمنية لفلترة البيانات التي تم تصديرها.تتطلّب هذه الأوامر رمز OAuth المميّز ومفتاح واجهة برمجة التطبيقات اللذين جمعتهما سابقًا.

البيانات من آخر عملية تصدير

يمكنك استخدام "فلاتر الوقت" مع "الوصول المستنِد إلى الوقت" لتصدير data الجديدة منذ آخر عملية تصدير. على سبيل المثال، نأخذ النطاق 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 الموقَّع في المتصفّح لتنزيل أرشيف البيانات. عليك examining the contents of the archive to ensure that it contains the expected search activity data.

ملاحظة: يعتمد الوقت اللازم لإكمال مهمة الأرشفة على حجم الأرشيف. الحد الأقصى للمدة هو سبعة أيام.

إذا تلقّيت حالة FAILED في الردّ، يمكنك إعادة محاولة التصدير باستخدام طريقة RetryPortabilityArchive.
انتظِر لمدة 24 ساعة على الأقل، ثم قدِّم طلبًا آخر إلى InitiatePortabilityArchive باستخدام الأمر نفسه المُستخدَم في الخطوة 1، ولكن استخدِم هذه المرة 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 وأنّك تريد تصدير data الأشهر الستة الماضية. أولاً، تُرسِل طلبًا مُعتمَدًا إلى نقطة نهاية 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 ل retrieving the status of the archive job.

نفِّذ الأمر 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 هو الطابع الزمني الذي تم فيه إجراء المكالمة إلى InitiatePortabilityArchive في الخطوة 1.
تأكَّد من أنّ عملية التصدير لا تحتوي إلا على بيانات من الأشهر الستة الماضية.

البيانات من فترة زمنية محدّدة

يمكنك استخدام "فلاتر الوقت" لتصدير البيانات من نطاق محدّد من التواريخ، مثل البيانات من عام 2023 فقط.

أولاً، تُرسِل طلبًا مصادقًا على نقطة نهاية 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 ل retrieving the status of the archive job.

نفِّذ الأمر 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.