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

تتيح لك Data Portability API إنشاء تطبيقات تطلب الإذن من العميل لنقل نسخة من البيانات من خدمات Google إلى تطبيقك. ويسمح ذلك بنقل البيانات وتسهيل تبديل الخدمات.

للحصول على معلومات عن كيفية مشاركة المستخدمين للبيانات، اطّلِع على مقالة مشاركة نسخة من بياناتك مع جهة خارجية.

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

قبل طرح تطبيقك، يجب أن توافق Google عليه.

عليك أيضًا التأكّد من توفّر واجهة برمجة التطبيقات Data Portability API للمستخدمين في موقعك الجغرافي. للحصول على قائمة بالبلدان والمناطق التي تتوفّر فيها هذه الميزة، يُرجى الاطّلاع على الأسئلة الشائعة في صفحة "مشاركة نسخة من بياناتك مع جهة خارجية".

سير عمل المطوّر

في ما يلي الخطوات التي يجب اتّباعها لإنشاء تطبيق يستخدم واجهة برمجة التطبيقات Data Portability API.

1. تنفيذ مسار الموافقة على OAuth للمستخدم في هذا المثال، يمنح المستخدم إذن الوصول إلى بيانات فيديوهات YouTube.

   1. ينقر المستخدم على استيراد فيديوهات YouTube ويُسجّل الدخول إلى حسابه على Google.

   2. يعيد التطبيق توجيه المستخدم إلى عنوان URL لموافقة OAuth. يُرجى العِلم أنّ مثال عنوان URL هذا مبسّط ولا يتضمّن بعض المَعلمات:

      https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/dataportability.myactivity.youtube

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

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

      ملاحظة: يمكن للمستخدم تجديد إذن وصولك إلى بياناته قبل انتهاء صلاحية رمز OAuth بمدة تصل إلى 90 يومًا. لا يظهر زر التجديد إذا لم يكن لدى المستخدم نطاقات تنتهي صلاحيتها خلال 90 يومًا.

   5. تتم إعادة توجيه المستخدم إلى التطبيق.

   6. يحصل المطوّر على رمز مميّز لبروتوكول OAuth للمستخدم.

2. يطلب تطبيقك InitiatePortabilityArchive(resources = ["myactivity.youtube"]) باستخدام رمز مميز لبروتوكول OAuth مرفق يحتوي على نطاق OAuth التالي:

   https://www.googleapis.com/auth/dataportability.myactivity.youtube

   يبدأ هذا الطلب عملية إنشاء أرشيف البيانات ويردّ بقيمة معرّف الوظيفة وما إذا كان المستخدم قد منَح إذن وصول لمرة واحدة أو إذن وصول مستندًا إلى الوقت.

   ملاحظة: يعني الوصول لمرة واحدة عملية تصدير واحدة لكل نطاق. إذا منح المستخدم نطاقات متعددة، يمكنك اختيار إنشاء مهام منفصلة لكلٍّ من الموارد التي يوافق عليها الرمز المميّز.

3. يطلب تطبيقك GetPortabilityArchiveState(job_id) باستخدام رمز أمان OAuth مرفق يحتوي على نطاق OAuth التالي:

   https://www.googleapis.com/auth/dataportability.myactivity.youtube

   يمكنك استدعاء هذه الطريقة عدة مرات لاسترداد حالة مهمة الأرشفة. تُعرِض الطريقة حالة المهمة. إذا كانت الحالة هي COMPLETE، يكون الأرشيف جاهزًا، ويتم توفير عناوين URL موقَّعة في Cloud Storage. يُرجى العِلم أنّه يمكن أن يختلف الوقت المستغرَق لإكمال طلب الأرشفة من دقائق إلى ساعات استنادًا إلى حجم البيانات.

4. نزِّل أرشيف البيانات باستخدام عناوين URL الموقَّعة.

5. إذا منح المستخدم إذن الوصول لمرة واحدة، يمكنك الاتصال بـ ResetAuthorization() باستخدام رمز مميّز OAuth مرفق لإعادة ضبط الموارد المستنفدة وإزالة كل موافقة OAuth.

6. إذا منح المستخدم إذن الوصول المستند إلى الوقت، يمكنك تصدير الموارد كل 24 ساعة إلى أن تنتهي صلاحية الموافقة.

لمزيد من المعلومات عن استخدام طرق Data Portability API، يُرجى الاطّلاع على مقالة استدعاء طرق Data Portability API.

كيفية تفاعل المستخدمين مع تطبيق يستخدم واجهة برمجة التطبيقات Data Portability API

يوضِّح هذا المخطّط البياني كيفية تفاعل المستخدمين مع تطبيق مدمج مع واجهة برمجة التطبيقات Data Portability API.

1. أولاً، يتم عرض خيار على المستخدم لاسترداد بياناته.

2. بعد ذلك، يسجّل المستخدم الدخول إلى حسابه على Google.

3. بعد ذلك، ينقر المستخدم على التالي عندما يُطلب منه مشاركة بياناته، ويُقرّ على أفهم عندما يُطلب منه قبول سياسة الخصوصية.

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

5. بعد السماح بالوصول، تبدأ عملية استيراد البيانات. استنادًا إلى حجم البيانات، يمكن أن يستغرق اكتمال الطلب عدة دقائق إلى عدة ساعات.