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

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

المعلومات التي تكتسبها

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

• يمكنك إرسال طلب تمت المصادقة عليه إلى نقطة نهاية 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 ومعرّف الموارد المنتظم (URI) لإعادة التوجيه (مثلاً، 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&
   include_granted_scopes=true&
   state=developer-specified-value
   

   في عنوان URL:

   • client_id هو معرِّف عميل OAuth.
   • redirect_uri هو معرّف الموارد المنتظم (URI) المعتمد لإعادة التوجيه، على سبيل المثال، https://google.com.

   لاحظ أن النطاق المستخدم في عنوان URL لبدء الاستخدام السريع هذا هو نطاق نشاط البحث. يمكنك أيضًا استخدام نطاق النشاط على YouTube أو كليهما.

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

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

   

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

4. للتحقّق من رمز 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"
   }
   

   ملاحظة: يمكنك أيضًا التحقّق من الرمز المميّز من خلال إصدار طلب HTTP GET.

5. اجمع رمز 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. يُستخدم معرف الوظيفة هذا لاسترداد حالة أرشيف البيانات.

   {
     "archiveJobId": "<your_job_id>"
   }
   

   إذا تعذَّر عليك توفير رمز 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 الوظيفة. إذا لم تكن المهمة مكتملة، فإن الرد يوفر الحالة الحالية. ينبغي عليك إرسال الطلبات إلى نقطة النهاية هذه بشكل دوري حتى تكتمل المهمة.

   {
     "state": "IN_PROGRESS"
   }
   

   إذا اكتملت المهمة، ستحتوي الاستجابة على الحالة وعنوان URL موقَّع واحد أو أكثر يتم استخدامها لتنزيل أرشيف البيانات.

   {
     "state": "COMPLETE",
     "urls": [
       "<signed_url>"
     ]
   }
   

   الصِق عنوان URL الذي تم تسجيله في المتصفّح لتنزيل أرشيف البيانات. عليك فحص محتوى الأرشيف للتأكد من أنّه يحتوي على بيانات نشاط البحث المتوقع.

   ملاحظة: تعتمد المدة الزمنية المطلوبة لإكمال مهمة الأرشفة على حجم الأرشيف. الحد الأقصى للمدة هو سبعة أيام.
   ملاحظة: في حال ظهور حالة 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": "Resource has been exhausted (check quota).",
     "status": "RESOURCE_EXHAUSTED"
   }
   

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"
     }