بدء استخدام واجهة برمجة التطبيقات Data Portability API

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

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

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

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

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

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

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

• تأكَّد من توفّر واجهة برمجة التطبيقات 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.
  • عند اختيار المدّة التي تريد السماح بالوصول خلالها، يستخدم الإعداد السريع إذن الوصول لمرة واحدة.
• الحصول على رمز OAuth
• الحصول على إذن الوصول إلى حساب مملوك لمؤسستك أو تخضع مؤسستك لرقابته يتم تصدير بيانات نشاط البحث لهذا الحساب في هذا الدليل السريع.

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

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

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

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

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

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

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

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

   

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

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

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

6. اجمع رمز 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_ONE_TIME'
   }
   

   في حال عدم تقديم رمز مميز صالح لبروتوكول 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. Please call ResetAuthorization and re-obtain consent before trying again.",
       "status": "RESOURCE_EXHAUSTED",
       "details": [
         {
           "@type": "type.googleapis.com/google.rpc.ErrorInfo",
           "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
           "domain": "dataportability.googleapis.com"
     "metadata": {
       "previous_job_ids": "{previous_job_ids}"
       "access_type": "ACCESS_TYPE_ONE_TIME"
   ...
   

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

   يعرض هذا الأمر استجابة فارغة.

5. (اختياري) بعد إعادة ضبط التفويض، أرسِل طلبًا آخر إلى نقطة نهاية 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"
     }