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

تتكوّن Data Portability API من الطريقتَين التاليتَين:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive
  • archiveJobs.cancelPortabilityArchive
  • accessType.check

portabilityArchive.initiate

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

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

archiveJobs.cancelPortabilityArchive

يتم استدعاء الطريقة archiveJobs.cancelPortabilityArchive لإلغاء مهمة individual job بدون إبطال الرموز المميّزة الحالية عندما يكون لديك إذن وصول مستمر إلى بيانات المستخدم. يكون هذا الإجراء مفيدًا عندما لا تكون هناك حاجة إلى وظيفة أو مورد وكنت تريد إعادة ضبط حصة وظائفك. يجب أن تكون الوظيفة IN_PROGRESS وأن يكون قد تم إنشاؤها باستخدام إذن وصول مستند إلى الوقت لإلغائها.

على سبيل المثال، يمكنك إلغاء مهمة قيد التنفيذ تستند إلى الوقت لملفين شخصيَّين myactivity.youtube وyoutube.public_videos ثم بدء مهمة جديدة لملف شخصي واحد فقط هو myactivity.youtube.

accessType.check

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

يحتوي الردّ على حقلَين: قوائم بمعرّفات مجموعات موارد نقل البيانات لمرة واحدة ومستندة إلى الوقت ومفوَّضة من خلال رمز OAuth المُستخدَم في الردّ. لا يمكن للمستخدمين مزج أنواع الوصول في منح الرمز المميّز، ولكن يجب عدم افتراض هذا السلوك في المستقبل.