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.

Áp dụng bộ lọc thời gian cho yêu cầu của bạn

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

Phần hướng dẫn bắt đầu nhanh này trình bày cách sử dụng Data Portability API với quyền truy cập dựa trên thời gian và áp dụng bộ lọc thời gian cho các tài nguyên được hỗ trợ. Để biết thêm thông tin chi tiết về quyền truy cập dựa trên thời gian vào dữ liệu người dùng, hãy xem bài viết Sử dụng quyền truy cập dựa trên 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 các yêu cầu đã xác thực định kỳ đến điểm cuối InitiatePortabilityArchive để chỉ xuất dữ liệu mới kể từ lần xuất gần đây nhất.
Gửi một yêu cầu đã xác thực đến điểm cuối InitiatePortabilityArchive để chỉ xuất dữ liệu trong 6 tháng qua.
Gửi yêu cầu đã xác thực đến điểm cuối InitiatePortabilityArchive để chỉ xuất dữ liệu trong một khoảng thời gian cụ thể.

Đ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 tính năng lọc thời gian bằng quyền truy cập dựa trên thời gian. (Bộ lọc thời gian cũng hoạt động với quyền truy cập một lần).
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:

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ó thể sử dụng mọi phạm vi hỗ trợ Bộ lọc theo thời gian.

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. (Bộ lọc thời gian cũng hoạt động với quyền truy cập một lần.)
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.

Lưu ý quan trọng: Mã thông báo truy cập OAuth của bạn sẽ hết hạn sau một giờ. Nếu bạn cần tạo mã thông báo mới, hãy làm theo các bước trước.
Để 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.

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ó dấu thời gian để lọc dữ liệu đã xuất.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 đó.

Dữ liệu từ lần xuất gần đây nhất

Bạn có thể sử dụng Bộ lọc thời gian với quyền truy cập dựa trên thời gian để xuất dữ liệu mới kể từ lần xuất gần đây nhất. Ví dụ: hãy xem xét phạm vi https://www.googleapis.com/auth/dataportability.myactivity.search.

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ữ cho toàn bộ tập hợp dữ liệu.

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 và hỗ trợ Bộ lọc theo thời gian. 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 hoặc các nhóm tài nguyên không được hỗ trợ, 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ề archiveJobId 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_1>"
  "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_1/portabilityArchiveState
```
Trong lệnh:
- your_OAuth_token là mã thông báo OAuth của bạn.
- your_job_id_1 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. Ngoài ra, còn có một trường export_time thể hiện dấu thời gian khi lệnh gọi đầu tiên đến InitiatePortabilityArchive được thực hiện.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
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.

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.
Đợi ít nhất 24 giờ rồi tạo một yêu cầu khác đến InitiatePortabilityArchive bằng cách sử dụng cùng một lệnh như ở bước 1, nhưng lần này hãy sử dụng export_time làm start_time.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Lưu ý: Bạn có thể điều chỉnh start_time để hơi chồng chéo với export_time nhằm đảm bảo mọi dữ liệu được tạo giữa các yêu cầu đều được đưa vào quá trình xuất.

Đối với quyền truy cập dựa trên thời gian, hàm này sẽ trả về:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Lặp lại bước 2 để gửi yêu cầu đã xác thực đến điểm cuối GetPortabilityArchiveState nhằm truy xuất trạng thái của công việc lưu trữ (sử dụng <your_job_id_2>).

Khi công việc hoàn tất, phản hồi sẽ là:

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

Xác minh rằng dữ liệu trong lượt xuất thứ hai chỉ chứa dữ liệu mới được tạo sau lượt xuất đầu tiên.

Dữ liệu trong 6 tháng qua

Bạn cũng có thể sử dụng Bộ lọc theo thời gian để chỉ xuất dữ liệu mới nhất thay vì toàn bộ kho văn bản.

Giả sử ngày hôm nay là 2024-10-01 và bạn muốn xuất dữ liệu trong 6 tháng qua. Trước tiên, bạn gửi một yêu cầu đã xác thực đến điểm cuối InitiatePortabilityArchive với start_time là "2024-04-01T00:00:00Z".

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"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Đối với quyền truy cập dựa trên thời gian, hàm này sẽ trả về:
```
{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Gửi yêu cầu đế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/job_id_1/portabilityArchiveState
```
Khi công việc hoàn tất, phản hồi sẽ là:
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}
```
Xin lưu ý rằng start_time là start_time được chỉ định ở bước 1 và export_time là dấu thời gian khi lệnh gọi đến InitiatePortabilityArchive được thực hiện ở bước 1.
Xác minh rằng tệp xuất chỉ chứa dữ liệu trong 6 tháng qua.

Dữ liệu trong một khoảng thời gian cụ thể

Bạn có thể sử dụng Bộ lọc theo thời gian để xuất dữ liệu từ một phạm vi ngày cụ thể, chẳng hạn như chỉ dữ liệu từ năm 2023.

Trước tiên, bạn gửi một yêu cầu đã xác thực đến điểm cuối InitiatePortabilityArchive với start_time là "2023-01-01T00:00:00Z" và end_time là "2023-12-31T23:59:59Z".

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"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Đối với quyền truy cập dựa trên thời gian, hàm này sẽ trả về:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Gửi yêu cầu đế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/job_id_1/portabilityArchiveState
```
Khi công việc hoàn tất, phản hồi sẽ là:
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}
```
Xin lưu ý rằng start_time là start_time được chỉ định ở bước 1 và export_time bằng với end_time được cung cấp ở bước 1.
Xác minh rằng tệp xuất chỉ chứa dữ liệu từ năm 2023.

Phạm vi được hỗ trợ

Các phạm vi sau đây hỗ trợ Bộ lọc thời gian:

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

Thận trọng: Các yêu cầu được lọc theo thời gian kết hợp các phạm vi được hỗ trợ và không được hỗ trợ sẽ dẫn đến lỗi INVALID_ARGUMENT cho biết The requested resources do not support time filters.