Sử dụng Quyền truy cập dựa trên thời gian

Trong hướng dẫn nhanh này, bạn sẽ lấy mã thông báo OAuth cho tài khoản của mình và gửi các yêu cầu định kỳ đến các điểm cuối của API Di chuyển dữ liệu.

Bài viết hướng dẫn nhanh này trình bày cách sử dụng Data Portability API để truy cập vào dữ liệu người dùng dựa trên thời gian. Để truy cập một lần vào dữ liệu người dùng, hãy xem phần Bắt đầu sử dụng Data Portability API. Để tìm hiểu cách áp dụng bộ lọc theo thời gian cho yêu cầu của bạn, hãy xem phần Áp dụng bộ lọc theo thời gian.

Kiến thức bạn sẽ học được

Trong phần bắt đầu nhanh này, bạn sẽ tìm hiểu cách:

  • Gửi yêu cầu đã xác thực đến điểm cuối InitiatePortabilityArchive bằng cách cung cấp mã thông báo OAuth hợp lệ. Phản hồi phải chứa một job_id hợp lệ.
  • Gửi yêu cầu đã xác thực đến điểm cuối GetPortabilityArchiveState. Phản hồi phải chứa trạng thái công việc hợp lệ và khi công việc hoàn tất, một URL đã ký.
  • Gửi yêu cầu đã xác thực bằng mã thông báo OAuth hợp lệ đến điểm cuối InitiatePortabilityArchive lần thứ hai bằng chính thông tin xác thực đó. Thao tác này sẽ trả về lỗi FAILED_PRECONDITION khi yêu cầu được thực hiện trong vòng 24 giờ kể từ yêu cầu ban đầu.

Điều kiện tiên quyết

Để chạy hướng dẫn bắt đầu nhanh này, bạn cần:

  • Xác minh rằng người dùng ở vị trí của bạn có thể sử dụng Data Portability API. Để xem danh sách các quốc gia và khu vực được hỗ trợ, hãy xem phần Câu hỏi thường gặp trên trang "Chia sẻ bản sao dữ liệu của bạn với bên thứ ba".
  • Hoàn tất các bước thiết lập cho Data Portability API.
  • Làm theo các bước để định cấu hình OAuth cho ứng dụng web JavaScript. Trong phiên bản chính thức, bạn thường sử dụng một luồng khác như luồng OAuth cho ứng dụng máy chủ web. Để đơn giản, hướng dẫn bắt đầu nhanh này sử dụng quy trình ứng dụng web JavaScript.
    • Khi bạn tạo thông tin xác thực uỷ quyền, hãy ghi lại Mã ứng dụng khách OAuth 2.0 và URI chuyển hướng được uỷ quyền (ví dụ: https://google.com). Bạn sẽ cần các thông tin này sau trong phần hướng dẫn nhanh.
    • Khi bạn định cấu hình phạm vi cho Data Portability API, hãy lưu ý rằng hướng dẫn nhanh này sử dụng nhóm tài nguyên myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
    • Khi chọn khoảng thời gian bạn muốn cho phép truy cập, bạn nên chọn 30 ngày để thử nghiệm quyền truy cập dựa trên thời gian.
  • Lấy mã thông báo OAuth.
  • Có quyền truy cập vào tài khoản do tổ chức của bạn sở hữu hoặc kiểm soát. Dữ liệu hoạt động tìm kiếm của tài khoản này sẽ được xuất trong phần hướng dẫn nhanh này.

Lấy mã thông báo OAuth

Trong phần hướng dẫn nhanh này, bạn sẽ gửi một yêu cầu uỷ quyền để lấy mã thông báo OAuth bằng một URL. Quy trình này sử dụng quy trình cho ứng dụng web JavaScript. Quy trình này không trả về mã thông báo làm mới.

Đối với ứng dụng chính thức, bạn thường sẽ sử dụng luồng OAuth để lấy mã thông báo làm mới có thể dùng để tạo mã thông báo truy cập theo yêu cầu. Ví dụ về điều này là quy trình cho ứng dụng web phía máy chủ.

Cách lấy mã thông báo OAuth:

  1. Soạn một URL như sau.

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value

    Trong URL:

    • client_id là mã ứng dụng khách OAuth của bạn.
    • redirect_uri là URI chuyển hướng được uỷ quyền của bạn; ví dụ: https://google.com.

    Lưu ý rằng phạm vi được sử dụng trong URL cho hướng dẫn nhanh này là phạm vi hoạt động tìm kiếm. Bạn cũng có thể sử dụng phạm vi hoạt động trên YouTube hoặc cả hai phạm vi.

  2. Dán URL đó vào thanh địa chỉ của trình duyệt rồi làm theo các bước trong quy trình OAuth. Quy trình này yêu cầu bạn đăng nhập vào tài khoản do tổ chức sở hữu hoặc kiểm soát mà bạn đang sử dụng cho phần hướng dẫn nhanh này.

    Đây là tài khoản đồng ý với các phạm vi OAuth. Màn hình yêu cầu đồng ý sẽ có dạng như sau (văn bản trên màn hình của bạn có thể khác với văn bản trong hình ảnh này):

    Màn hình yêu cầu sự đồng ý, trong đó người dùng đồng ý cho phép truy cập vào dữ liệu hoạt động tìm kiếm

  3. Chọn phạm vi cấp quyền truy cập và thời lượng chia sẻ quyền truy cập vào dữ liệu của tài khoản (một lần, 30 ngày hoặc 180 ngày). Đối với phần bắt đầu nhanh này, hãy chọn 30 ngày.

  4. Sau khi cấp quyền đồng ý và quyết định thời lượng truy cập, bạn sẽ được chuyển hướng đến URI chuyển hướng – https://google.com. URL được tạo trong thanh địa chỉ bao gồm mã truy cập OAuth.

    Ví dụ: nếu tài khoản người dùng cấp quyền truy cập OAuth vào phạm vi dataportability.myactivity.search, thì URL được tạo sẽ có dạng như sau:

    https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

    Trong URL, your_OAuth_token là một chuỗi đại diện cho mã thông báo.

  5. Để xác thực mã thông báo OAuth, hãy dán URL này vào trình duyệt:

    https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

    Phản hồi sẽ có dạng như sau:

    {
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}

    Bạn không cần trường azp hoặc aud để tạo yêu cầu. Trường azp đại diện cho client_id của người trình bày được uỷ quyền và trường aud xác định đối tượng mà mã thông báo này dành cho, tương đương với một trong các mã ứng dụng khách cho ứng dụng của bạn.

  6. Thu thập mã thông báo OAuth và khoá API. Bạn cần những thông tin này để thực hiện lệnh gọi đến Data Portability API.

Gửi yêu cầu đến các điểm cuối

Trong phần hướng dẫn nhanh này, bạn sẽ sử dụng các lệnh curl để gọi các điểm cuối API Di chuyển dữ liệu. Các lệnh này yêu cầu mã thông báo OAuth và khoá API mà bạn đã thu thập trước đó.

Cách gọi Data Portability API:

  1. Trước tiên, bạn gửi một yêu cầu đã xác thực đến điểm cuối InitiatePortabilityArchive. Yêu cầu này bắt đầu một công việc lưu trữ.

    Chạy lệnh curl sau:

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    Trong lệnh:

    • your_OAuth_token là mã thông báo OAuth của bạn.

    Yêu cầu InitiatePortabilityArchive trả về job_id và accessType. Mã công việc được dùng để truy xuất trạng thái của bản lưu trữ dữ liệu và loại quyền truy cập xác định xem bạn đã được cấp quyền truy cập một lần hay dựa trên thời gian đối với dữ liệu. Đối với quyền truy cập dựa trên thời gian, bạn sẽ thấy:

    {
  "archiveJobId": "<your_job_id>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

    Nếu bạn không cung cấp mã thông báo OAuth hợp lệ, thông báo lỗi này sẽ được trả về: 

    Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.

  2. Tiếp theo, bạn gửi một yêu cầu đã xác thực đến điểm cuối GetPortabilityArchiveState để truy xuất trạng thái của công việc lưu trữ.

    Chạy lệnh curl sau:

    curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState

    Trong lệnh:

    • your_OAuth_token là mã thông báo OAuth của bạn.
    • your_job_id là mã công việc do yêu cầu InitiatePortabilityArchive trả về.

    Phản hồi dựa trên trạng thái của công việc. Nếu công việc chưa hoàn tất, phản hồi sẽ cung cấp trạng thái hiện tại. Bạn nên gửi yêu cầu đến điểm cuối này theo định kỳ cho đến khi công việc hoàn tất.

    {
  "state": "IN_PROGRESS"
}

    Nếu công việc đã hoàn tất, phản hồi sẽ chứa trạng thái và một hoặc nhiều URL đã ký được dùng để tải bản lưu trữ dữ liệu xuống.

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}

    Dán URL đã ký vào trình duyệt để tải tệp lưu trữ dữ liệu xuống. Bạn nên kiểm tra nội dung của tệp lưu trữ để đảm bảo rằng tệp đó chứa dữ liệu hoạt động tìm kiếm dự kiến.

    Nếu nhận được trạng thái FAILED trong phản hồi, bạn có thể thử xuất lại bằng phương thức RetryPortabilityArchive.

  3. Lặp lại lệnh trước đó để gửi yêu cầu đã xác thực đến điểm cuối InitiatePortabilityArchive.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    Trong lệnh:

    • your_OAuth_token là mã thông báo OAuth của bạn.

    Phản hồi sẽ cho biết rằng bạn đã xuất tài nguyên myactivity.search và dấu thời gian cho thời điểm bạn có thể thử lại.

    ...
  "error": {
    "code": 429,
    "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...