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

Bắt đầu sử dụng Data Portability API (API Khả năng di chuyển dữ liệu)

Trong hướng dẫn bắt đầu 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 yêu cầu đến các điểm cuối của API Khả năng chuyển đổi dữ liệu.

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

Trong phần hướng dẫ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 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à một URL đã ký khi công việc hoàn tất.
(Không bắt buộc) Gửi một yêu cầu đã xác thực có mã thông báo OAuth hợp lệ đến điểm cuối InitiatePortabilityArchive lần thứ hai bằng cách sử dụng cùng một thông tin đăng nhập. Thao tác này sẽ trả về lỗi RESOURCE_EXHAUSTED và nhằm làm nổi bật tầm quan trọng của điểm cuối ResetAuthorization.
Gửi yêu cầu đã xác thực đến điểm cuối ResetAuthorization. Yêu cầu này thu hồi tất cả các phạm vi OAuth do người dùng cấp.
(Không bắt buộc) Gửi yêu cầu đến điểm cuối InitiatePortabilityArchive bằng chính mã thông báo OAuth bạn đã dùng trước đó. Yêu cầu sẽ không thành công sau khi đặt lại lệnh uỷ quyền.

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

Để chạy quy trình khởi động 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 API Khả năng di chuyển dữ liệu. Để biết danh sách các quốc gia và khu vực được hỗ trợ, hãy xem phần Các 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 thành các bước thiết lập cho API Dữ liệu có thể chuyển đổi.
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 các ứng dụng máy chủ web. Để đơn giản hoá, quá trình khởi động nhanh này sẽ sử dụng luồng ứng dụng web JavaScript.
- Khi bạn tạo thông tin xác thực cấp 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 chúng sau trong phần bắt đầu nhanh.
- Khi bạn định cấu hình phạm vi cho API Khả năng di chuyển dữ liệu, hãy lưu ý rằng hướng dẫn nhanh này sẽ sử dụng nhóm tài nguyên myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
Lấy mã thông báo OAuth.
Lấy 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 về hoạt động tìm kiếm của tài khoản này được xuất trong quá trình bắt đầu nhanh này.

Nhận mã thông báo OAuth

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

Đối với ứng dụng chính thức, bạn thường sử dụng luồng OAuth để lấy mã làm mới có thể dùng để tạo mã truy cập theo yêu cầu. Ví dụ như luồng cho các ứ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&
include_granted_scopes=true&
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 bạn uỷ quyền; ví dụ: https://google.com.
Xin lưu ý rằng phạm vi được dùng trong URL để bắt đầu 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.
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 của bạn sở hữu hoặc kiểm soát mà bạn đang dùng để bắt đầu nhanh này.

Đây là tài khoản đồng ý sử dụng các phạm vi OAuth. Màn hình xin phép sẽ có dạng như sau (văn bản trên màn hình có thể khác với văn bản trong hình ảnh này):
Sau khi đồng ý, bạn sẽ được chuyển tiếp đến URI chuyển hướng — https://google.com. URL được tạo trong thanh địa chỉ có chứa mã truy cập OAuth.

Ví dụ: nếu tài khoản người dùng cấp cho OAuth quyền truy cập 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ã 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 của bạn:

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

Thu thập mã thông báo OAuth và khoá API của bạn. Bạn cần có những mã này để thực hiện lệnh gọi đến Data Portability API (API Khả năng chuyển đổi dữ liệu).

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

Trong hướng dẫn bắt đầu nhanh này, bạn sử dụng lệnh curl để gọi các điểm cuối của API Khả năng chuyển đổi dữ liệu. Những 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 API Khả năng di chuyển dữ liệu:

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 sẽ bắt đầu một công việc lưu trữ.

Chạy lệnh curl sau đây:
```
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.
LƯU Ý: 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 bổ sung, hàm sẽ trả về lỗi.

Yêu cầu InitiatePortabilityArchive trả về một job_id. Mã công việc này dùng để truy xuất trạng thái của kho lưu trữ dữ liệu.
```
{
  "archiveJobId": "<your_job_id>"
}
```
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 đây:
```
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 state 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 định kỳ gửi các yêu cầu đến điểm cuối này 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ý dùng để tải kho 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 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 tệp lưu trữ. Thời lượng tối đa là 7 ngày.
Lưu ý: Nếu nhận được trạng thái FAILED trong phản hồi, thì bạn có thể thử xuất lại bằng phương thức RetryPortabilityArchive.

(Không bắt buộc) Lặp lại lệnh trước đó để gửi một 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 người dùng này đã hết quyền đồng ý một lần đối với tài nguyên myactivity.search.

...
  "error":
    {
      "code": 429,
  "message": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

Gửi một yêu cầu đã xác thực đến điểm cuối ResetAuthorization. Yêu cầu này sẽ thu hồi tất cả phạm vi OAuth do người dùng cấp và cho phép bạn gọi InitiatePortabilityArchive cho một nhóm tài nguyên mà bạn đã sử dụng.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
Trong lệnh:
- your_OAuth_token là mã thông báo OAuth của bạn.
Lệnh này trả về phản hồi trống.

(Không bắt buộc) Sau khi đặt lại quyền, hãy gửi một yêu cầu khác đến điểm cuối InitiatePortabilityArchive. Sử dụng chính lệnh curl mà bạn đã dùng trước đó.

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ẽ trả về lỗi vì mã thông báo OAuth bạn cung cấp đã bị thu hồi.

...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }