Phương thức API Khả năng di chuyển dữ liệu cuộc gọi

Data Portability API bao gồm các phương thức sau:

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

portabilityArchive.initiate

Bạn gọi phương thức portabilityArchive.initiate để bắt đầu một công việc xuất dữ liệu mới.

Khi bắt đầu một công việc xuất để tạo bản lưu trữ dữ liệu, bạn phải yêu cầu nhóm tài nguyên thích hợp và cung cấp mã thông báo OAuth có các phạm vi bắt buộc cho nhóm tài nguyên đó. Mã thông báo OAuth được dùng để uỷ quyền cho yêu cầu và xác định dữ liệu người dùng nào đang được xuất.

Để biết danh sách tất cả các nhóm tài nguyên mà một dịch vụ cụ thể hỗ trợ, hãy xem trang tham khảo giản đồ cho dịch vụ đó.

Ví dụ: nếu đang xuất dữ liệu hoạt động tìm kiếm, bạn sẽ gọi InitiatePortabilityArchive(resources = ["myactivity.search"]). Yêu cầu phải có mã thông báo OAuth được đính kèm với phạm vi OAuth tìm kiếm: https://www.googleapis.com/auth/dataportability.myactivity.search.

Mặc dù có thể đưa nhiều nhóm tài nguyên vào một lệnh gọi InitiatePortabilityArchive, nhưng bạn không nên làm như vậy. Bạn có thể đạt được tốc độ xử lý nhanh hơn bằng cách tạo các yêu cầu InitiatePortabilityArchive riêng biệt cho từng nhóm tài nguyên. Xin lưu ý rằng khi bạn yêu cầu nhiều nhóm tài nguyên, mã thông báo OAuth đính kèm phải có tất cả các phạm vi thích hợp được đính kèm.

Ví dụ: thay vì gọi InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) để tạo một bản lưu trữ dữ liệu cho cả hoạt động tìm kiếm và hoạt động trên YouTube, hãy thực hiện các lệnh gọi riêng biệt: InitiatePortabilityArchive(resources = ["myactivity.search"]) và InitiatePortabilityArchive(resources = ["myactivity.youtube"]).

Yêu cầu InitiatePortabilityArchive trả về một job_id. Mã công việc này được dùng để truy xuất trạng thái của bản lưu trữ dữ liệu.

archiveJobs.getPortabilityArchiveState

Phương thức archiveJobs.getPortabilityArchiveState được gọi để truy xuất trạng thái hiện tại của công việc xuất bản lưu trữ dữ liệu. Khi gọi getPortabilityArchiveState, bạn sẽ cung cấp job_id: GetPortabilityArchiveState(job_id). Bạn cũng phải cung cấp mã thông báo OAuth có phạm vi khớp với các nhóm tài nguyên được sử dụng trong yêu cầu initiate.

Nếu trạng thái là COMPLETE, các URL Cloud Storage đã ký sẽ được trả về mà bạn có thể sử dụng để tải dữ liệu xuống. URL đã ký sẽ hết hạn sau 6 giờ và dữ liệu sẽ có sẵn trong 14 ngày.

Yêu cầu lưu trữ có thể mất vài phút, vài giờ hoặc thậm chí vài ngày để hoàn tất, tuỳ thuộc vào lượng dữ liệu. Bạn có thể kiểm tra trạng thái của bản lưu trữ sau mỗi 5 đến 60 phút.

resetAuthorization

Phương thức resetAuthorization thực hiện những việc sau:

  • Thu hồi tất cả phạm vi OAuth do người dùng cấp
  • Cho phép ứng dụng gọi InitiatePortabilityArchive cho một nhóm tài nguyên mà bạn đã sử dụng trước đó
  • Xoá quyền truy cập vào các bản lưu trữ dữ liệu trước đó

Khi gọi resetAuthorization, bạn phải cung cấp mã thông báo OAuth đính kèm cho người dùng mà bạn đang đặt lại quyền uỷ quyền.

archiveJobs.retryPortabilityArchive

Phương thức archiveJobs.retryPortabilityArchive được gọi để thử lại các công việc không thành công, trong đó phương thức archiveJobs.getPortabilityArchiveState đã trả về trạng thái là FAILED. Điều này có thể xảy ra do lỗi tạm thời ở phần phụ trợ. Trong trường hợp đó, bạn có thể thử xuất lại mà không cần lấy mã thông báo OAuth mới từ người dùng. Khi gọi retryPortabilityArchive, bạn sẽ cung cấp job_id cùng với mã thông báo OAuth hợp lệ. Sau đó, điểm cuối sẽ cố gắng tạo một tệp xuất cho cùng một nhóm tài nguyên được yêu cầu trong yêu cầu initiatePortabilityArchive ban đầu. Nếu thành công, điểm cuối này sẽ trả về một job_id mới mà bạn có thể sử dụng trong các lệnh gọi đến getPortabilityArchiveState. Bạn có thể thử lại một công việc không thành công tối đa 3 lần.

Ví dụ:

  1. Bạn gọi InitiatePortabilityArchive(resources = ["myactivity.search"]) và nhận được job_id: 0.

  2. Sau khi gọi GetPortabilityArchiveState(0), bạn sẽ nhận được JobSate: FAILED.

  3. Sau đó, bạn có thể gọi RetryPortabilityArchive(0) để nhận job_id: 1 cho resources = ["myactivity.search"].

  4. Sau đó, bạn có thể tiếp tục gọi đến GetPortabilityArchiveState(1).

archiveJobs.cancelPortabilityArchive

Phương thức archiveJobs.cancelPortabilityArchive được gọi để huỷ một công việc riêng lẻ mà không thu hồi các mã thông báo hiện có khi bạn có quyền truy cập liên tục vào dữ liệu người dùng. Việc này hữu ích khi bạn không cần công việc hoặc tài nguyên nữa và muốn đặt lại hạn mức công việc. Công việc phải là IN_PROGRESS và được tạo bằng quyền truy cập dựa trên thời gian thì mới có thể huỷ.

Ví dụ: bạn có thể huỷ một công việc đang diễn ra, dựa trên thời gian cho myactivity.youtube và youtube.public_videos, sau đó bắt đầu một công việc mới chỉ dành cho myactivity.youtube.

accessType.check

Phương thức accessType.check cho phép bạn kiểm tra xem mã thông báo OAuth có cho phép truy cập dựa trên thời gian hay truy cập một lần trước khi bắt đầu công việc hay không. Ví dụ: bạn có thể dự định xuất toàn bộ nhật ký của người dùng nếu họ cấp quyền truy cập một lần hoặc chỉ ngày cuối cùng nếu họ cấp quyền truy cập dựa trên thời gian.

Phản hồi chứa hai trường: danh sách mã nhận dạng nhóm tài nguyên có khả năng di chuyển dữ liệu một lần và dựa trên thời gian do mã thông báo OAuth được dùng trong yêu cầu uỷ quyền. Người dùng không thể kết hợp các loại quyền truy cập trong một lần cấp mã thông báo, nhưng bạn không nhất thiết phải giả định hành vi đó trong tương lai.