روش‌های API انتقال داده‌ها را فراخوانی کنید

Data Portability API از این روش ها تشکیل شده است:

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

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 برای بازیابی وضعیت فعلی کار صادرات بایگانی داده فراخوانی می شود. هنگامی که با getPortabilityArchiveState تماس می گیرید، job_id را ارائه می کنید: GetPortabilityArchiveState(job_id) . همچنین باید یک توکن OAuth با دامنه‌هایی که با گروه‌های منابع مورد استفاده در درخواست initiate مطابقت دارد، ارائه دهید.

اگر وضعیت COMPLETE باشد، نشانی‌های وب امضا شده ذخیره‌سازی ابری بازگردانده می‌شوند که می‌توانید برای دانلود داده‌ها از آنها استفاده کنید. 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 برای لغو یک کار فردی بدون لغو نشانه‌های موجود در زمانی که دسترسی مداوم به داده‌های کاربر دارید فراخوانی می‌شود. این زمانی مفید است که دیگر به شغل یا منبعی نیاز نیست و می خواهید سهمیه شغلی خود را تنظیم مجدد کنید. کار باید IN_PROGRESS باشد و با دسترسی مبتنی بر زمان ایجاد شده باشد تا لغو شود.

برای مثال، می‌توانید یک کار در حال انجام و مبتنی بر زمان را برای myactivity.youtube و youtube.public_videos لغو کنید، سپس یک کار جدید را فقط برای myactivity.youtube شروع کنید.

accessType.check

روش accessType.check به شما امکان می دهد قبل از شروع کار بررسی کنید که آیا یک نشانه OAuth اجازه دسترسی مبتنی بر زمان یا یک بار را می دهد. به عنوان مثال، ممکن است قصد داشته باشید که کل تاریخچه کاربر را در صورت اعطای یک بار دسترسی، یا فقط روز آخر در صورت اعطای دسترسی مبتنی بر زمان، صادر کنید.

پاسخ شامل دو فیلد است: فهرست شناسه‌های گروه منبع قابلیت انتقال داده یک‌باره و مبتنی بر زمان که توسط توکن OAuth استفاده شده در درخواست مجاز است. کاربران نمی توانند انواع دسترسی را در یک اعطای توکن ترکیب کنند، اما لزوماً نباید این رفتار را در آینده فرض کنید.