طرق واجهة برمجة التطبيقات الخاصة بنقل بيانات المكالمات

تتكوّن واجهة برمجة التطبيقات Data Portability API من الطرق التالية:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive

portabilityArchive.initiate

يمكنك استدعاء الطريقة portabilityArchive.initiate لبدء مهمة تصدير بيانات جديدة.

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

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

على سبيل المثال، عند تصدير بيانات سجلّ البحث، يمكنك استدعاء InitiatePortabilityArchive(resources = ["myactivity.search"]). يجب أن يحتوي الطلب على رمز OAuth مميز مرتبط بنطاق OAuth للبحث: https://www.googleapis.com/auth/dataportability.myactivity.search.

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

على سبيل المثال، بدلاً من استدعاء InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) لإنشاء أرشيف بيانات لكل من البحث والنشاط على YouTube، يمكنك إجراء هذه الطلبات المنفصلة: InitiatePortabilityArchive(resources = ["myactivity.search"]) وInitiatePortabilityArchive(resources = ["myactivity.youtube"]).

يعرض طلب InitiatePortabilityArchive خطأ job_id. يُستخدم معرف الوظيفة هذا لاسترداد حالة أرشيف البيانات.

archiveJobs.getPortabilityArchiveState

يتم استدعاء الطريقة archiveJobs.getPortabilityArchiveState لاسترداد state الحالية لمهمة تصدير أرشيف البيانات. عند الاتصال بـ getPortabilityArchiveState، يتم تقديم job_id: GetPortabilityArchiveState(job_id). يجب أيضًا توفير رمز OAuth مميز مع نطاقات تتطابق مع مجموعات الموارد المستخدمة في طلب initiate.

إذا كانت الحالة هي "COMPLETE"، يتم عرض عناوين URL الموقَّعة في Cloud Storage ويمكنك استخدامها لتنزيل البيانات. تنتهي صلاحية عناوين URL الموقَّعة بعد ست ساعات، وتصبح البيانات متاحة لمدة 14 يومًا.

قد يستغرق طلب الأرشفة عدة دقائق أو ساعات متعددة أو حتى عدة أيام حسب حجم البيانات. يمكنك التحقق من حالة الأرشيف كل خمس إلى 60 دقيقة.

resetAuthorization

تؤدي طريقة resetAuthorization إلى ما يلي:

  • يوقف جميع نطاقات OAuth التي يمنحها المستخدم
  • يسمح للتطبيق بالاتصال بـ InitiatePortabilityArchive لمجموعة موارد استخدمتها في السابق
  • إزالة إمكانية الوصول إلى أرشيفات البيانات السابقة

عند طلب اتصال بـ resetAuthorization، يجب تقديم رمز OAuth مميز مرفق للمستخدم الذي تتم إعادة ضبط تفويضه.

archiveJobs.retryPortabilityArchive

يتم استدعاء الإجراء archiveJobs.retryPortabilityArchive لإعادة محاولة تنفيذ المهام التي تعذّر تنفيذها إذا كانت طريقة archiveJobs.getPortabilityArchiveState قد عرضت state لـ FAILED. قد يحدث هذا بسبب عطل مؤقت في الخلفية. وفي هذه الحالة، يمكنك إعادة محاولة التصدير بدون الحصول على رمز OAuth جديد من المستخدم. عند الاتصال بـ retryPortabilityArchive، يمكنك تقديم job_id مع رمز OAuth مميز صالح. بعد ذلك، تحاول نقطة النهاية إنشاء عملية تصدير لمجموعات الموارد نفسها المطلوبة في طلب initiatePortabilityArchive الأولي. في حال نجاح هذا الإجراء، تعرض نقطة النهاية هذه job_id جديدة يمكنك استخدامها في المكالمات إلى getPortabilityArchiveState. يمكن إعادة المحاولة ثلاث مرات كحدّ أقصى مع أي وظيفة غير ناجحة.

مثال:

  1. اتصلت بـ InitiatePortabilityArchive(resources = ["myactivity.search"])، وتلقيت job_id: 0.

  2. بعد الاتصال برقم GetPortabilityArchiveState(0)، ستصلك رسالة إلكترونية تتضمّن JobSate: FAILED.

  3. يمكنك بعد ذلك الاتصال بالرقم RetryPortabilityArchive(0) لتلقّي job_id: 1 مقابل resources = ["myactivity.search"].

  4. بعد ذلك، يمكنك مواصلة إجراء المكالمات على الرقم GetPortabilityArchiveState(1).