Chúng tôi đang triển khai các tính năng mới của Data Portability API và sẽ cung cấp cho tất cả mọi người muộn nhất vào ngày 20 tháng 2 năm 2025!

Trang này được dịch bởi Cloud Translation API.

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 phía máy chủ.
- 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, mật khẩu ứng dụng khách 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 trong phần sau của 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 phía máy chủ. Quy trình này sẽ tạo một mã thông báo làm mới mà bạn có thể sử dụng cho các lần xuất tiếp theo.

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

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=code&
access_type=offline&
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.

Cảnh báo: Đừng kết hợp các phạm vi API Di chuyển dữ liệu với các loại phạm vi khác, sử dụng quá nhiều phạm vi cùng một lúc hoặc đưa vào các phạm vi đã cấp trước đó vì điều này sẽ dẫn đến lỗi. Để biết thông tin chi tiết, hãy xem phần Hạn chế về phạm vi.
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):
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.
Sau khi đồ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ột mã uỷ quyền mà bạn sẽ trao đổi lấy mã thông báo OAuth ở bước tiếp theo.

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&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
Để trao đổi mã uỷ quyền lấy mã truy cập, hãy gọi điểm cuối mã thông báo oauth bằng:
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'
```
Phản hồi sẽ có dạng như sau:
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}
```
Trong URL, your_OAuth_token là một chuỗi đại diện cho mã thông báo.

Trường refresh_token_expires_in tính bằng giây và cho biết người dùng đã chọn quyền truy cập trong 30 ngày (2592000 giây) hay 180 ngày (15552000 giây). Nếu ứng dụng của bạn có trạng thái phát hành là Thử nghiệm, thì bạn sẽ có quyền truy cập trong 7 ngày (604800 giây) bất kể người dùng chọn gì.

Lưu ý quan trọng: Mã truy cập OAuth của bạn sẽ hết hạn sau một giờ. Hãy lưu trữ mã làm mới để có thể đổi lấy mã truy cập mới sau này.
Để 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 các 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 cho ứng dụng của bạn.

Lưu ý: Bạn cũng có thể xác minh mã thông báo bằng cách đưa ra yêu cầu GET HTTP.
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:

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.
Cảnh báo: Tham số resources chỉ được chứa các phạm vi OAuth đã được cấp quyền truy cập. Trong ví dụ này, chỉ myactivity.search được cấp. Nếu bạn thêm các nhóm tài nguyên khác, hệ thống sẽ trả về lỗi. Để biết thông tin chi tiết, hãy xem phần Hạn chế về phạm vi.

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.
```
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 đị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 bản lưu trữ để đảm bảo rằng bản lưu trữ đó chứa dữ liệu hoạt động tìm kiếm dự kiến.

Lưu ý: Khoảng thời gian cần thiết để hoàn tất công việc lưu trữ phụ thuộc vào kích thước của bản lưu trữ. Thời lượng tối đa là 7 ngày.

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.

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}"
...

Sau 24 giờ, bạn có thể yêu cầu xuất dữ liệu mới, nhưng trước tiên, bạn phải hoán đổi mã làm mới lấy mã truy cập mới.
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'
```
Phản hồi sẽ có dạng như sau:
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}
```
Nếu người dùng gia hạn quyền truy cập, thì thời gian hết hạn mới sẽ được phản ánh trong trường refresh_token_expires_in.

Bạn có thể sử dụng mã thông báo truy cập mới để lặp lại các bước InitiatePortabilityArchive và GetPortabilityArchiveState.