استخدام الوصول المستند إلى الوقت

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

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

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

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

• أرسِل طلبًا تمّت مصادقته إلى نقطة النهاية InitiatePortabilityArchive من خلال تقديم رمز OAuth صالح. يجب أن يحتوي الردّ على قيمة job_id صالحة.
• أرسِل طلبًا تمّت مصادقته إلى نقطة النهاية GetPortabilityArchiveState. يجب أن يحتوي الردّ على حالة مهمة صالحة، وعند اكتمال المهمة، يجب أن يتضمّن عنوان URL موقَّعًا.
• أرسِل طلبًا تمّت مصادقته باستخدام رمز مميّز صالح لبروتوكول OAuth إلى نقطة نهاية InitiatePortabilityArchive مرة أخرى باستخدام بيانات الاعتماد نفسها. يؤدي ذلك إلى عرض خطأ FAILED_PRECONDITION عند إرسال الطلب في غضون 24 ساعة من الطلب الأول.

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

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

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

الحصول على رمز OAuth

في هذه المقالة السريعة، سترسل طلب مصادقة للحصول على رمز مميز لبروتوكول OAuth باستخدام عنوان URL. تستخدِم هذه العملية مسار تطبيقات الويب من جهة الخادم. يؤدي هذا الإجراء إلى إنشاء رمز إعادة تصعيد يمكنك استخدامه في عمليات التصدير اللاحقة.

للحصول على رمز OAuth المميّز:

1. اكتب عنوان 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 أو كلا النطاقَين.

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

2. الصِق عنوان URL في شريط العناوين في المتصفّح واتّبِع الخطوات الواردة في خطوات ملف تعريف الارتباط المتوافق مع OAuth. تتطلّب هذه العملية تسجيل الدخول إلى الحساب الذي تملكه مؤسستك أو تتحكم فيه والذي تستخدمه في هذه الخطوة السريعة.

   هذا هو الحساب الذي يوافق على نطاقات OAuth. من المفترض أن تظهر شاشة الموافقة على النحو التالي (قد يختلف النص في شاشتك عن النص في هذه الصورة):

   

3. اختَر النطاقات التي تريد منح إذن الوصول إليها ومدّة مشاركة إذن الوصول إلى بيانات الحساب (لمرة واحدة أو 30 يومًا أو 180 يومًا). في هذه الخطوة السريعة، اختَر 30 يومًا.

4. بعد منح الموافقة وتحديد مدة الوصول، من المفترض أن تتم إعادة توجيهك إلى عنوان URL لإعادة التوجيه: https://google.com. يتضمّن عنوان URL الذي يتم إنشاؤه في شريط العناوين رمز تفويض يتم تبديله برمز مميّز لبروتوكول 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

5. لتبديل رمز التفويض برمز مميّز للوصول، استخدِم نقطة نهاية رمز مميّز oauth مع:

   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 بعد ساعة واحدة، لذا عليك تخزين رمز إعادة التحديث لكي تتمكّن من استبداله برموز وصول جديدة لاحقًا.

6. للتحقّق من صحة رمز 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.

7. اجمع رمز OAuth المميّز ومفتاح واجهة برمجة التطبيقات. ستحتاج إلى هذه العناصر لإجراء اتصالات بواجهة برمجة التطبيقات Data Portability API.

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

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

لاستدعاء Data Portability API:

1. أولاً، تُرسِل طلبًا مُعتمَدًا إلى نقطة نهاية 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.

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

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

   إذا تلقّيت حالة FAILED في الردّ، يمكنك إعادة محاولة التصدير باستخدام طريقة RetryPortabilityArchive.

3. كرِّر الأمر السابق لإرسال طلب تمّت مصادقته إلى نقطة نهاية 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}"
   ...
   

4. بعد 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.