Authentication

Tài liệu này mô tả cách xác thực với API Ad Manager. Cách bạn xác thực phụ thuộc vào giao diện bạn sử dụng và môi trường nơi mã của bạn đang chạy, nhưng tất cả yêu cầu API phải bao gồm mã truy cập có phạm vi API Ad Manager.

Thư viện ứng dụng Ad Manager sử dụng Thông tin xác thực mặc định của ứng dụng để tạo mã truy cập có phạm vi API Ad Manager. Hướng dẫn này trình bày cách định cấu hình Thông tin xác thực mặc định của ứng dụng.

Nếu không sử dụng thư viện ứng dụng, bạn vẫn cần tạo thông tin xác thực và sử dụng thông tin đó để uỷ quyền cho các yêu cầu của mình.

Để biết thêm thông tin về việc xác thực và uỷ quyền, hãy xem hướng dẫn Sử dụng OAuth 2.0.

Xác định loại xác thực

Loại xác thực Mô tả
Tài khoản dịch vụ Chọn mục này nếu bạn muốn xác thực bằng tài khoản chuyên dụng thay vì một người cụ thể.
Tìm hiểu thêm.
Ứng dụng web Chọn chế độ này nếu bạn muốn xác thực với tư cách là bất kỳ người dùng nào cấp quyền cho ứng dụng của bạn truy cập vào dữ liệu Ad Manager của họ.
Tìm hiểu thêm
Phát triển tại địa phương Chọn tuỳ chọn này nếu bạn muốn xác thực bằng Tài khoản Google của riêng mình hoặc Tài khoản dịch vụ trong môi trường phát triển cục bộ.

Bật API Ad Manager

  1. Bật API Ad Manager trong Dự án trên đám mây của Google API Console.

  2. Nếu bạn nhận được lời nhắc, hãy chọn một dự án hoặc tạo dự án mới.

Tạo thông tin đăng nhập

Nhấp vào thẻ cho loại xác thực của bạn và làm theo hướng dẫn để tạo thông tin xác thực:

Tài khoản dịch vụ

Trên Google Cloud

Để xác thực một khối lượng công việc đang chạy trên Google Cloud, bạn sử dụng thông tin đăng nhập của tài khoản dịch vụ được đính kèm vào tài nguyên điện toán nơi mã của bạn đang chạy.

Ví dụ: bạn có thể đính kèm tài khoản dịch vụ vào một thực thể máy ảo (VM) Compute Engine, một dịch vụ Cloud Run hoặc một công việc Dataflow. Đây là phương pháp xác thực ưu tiên cho mã chạy trên tài nguyên điện toán của Google Cloud.

Để biết thông tin về những tài nguyên mà bạn có thể đính kèm tài khoản dịch vụ và được trợ giúp về việc đính kèm tài khoản dịch vụ vào tài nguyên, hãy xem tài liệu về cách đính kèm tài khoản dịch vụ.

Tại cơ sở hoặc trên một nhà cung cấp dịch vụ đám mây khác

Phương thức ưu tiên để thiết lập quy trình xác thực từ bên ngoài Google Cloud là sử dụng Workload Identity Federation; bạn tạo một tệp cấu hình thông tin xác thực và đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS để trỏ đến tệp đó. Phương pháp này an toàn hơn so với việc tạo khoá tài khoản dịch vụ.

Nếu không thể định cấu hình phương thức liên kết Workload Identity, thì bạn phải tạo một tài khoản dịch vụ và tạo khoá cho tài khoản dịch vụ đó:

  1. Mở trang Thông tin xác thực của Google API Console.

  2. Trên trang Thông tin xác thực, hãy chọn Tạo thông tin xác thực, sau đó chọn Tài khoản dịch vụ.

  3. Nhấp vào địa chỉ email của tài khoản dịch vụ mà bạn muốn tạo khoá.

  4. Nhấp vào thẻ Khoá.

  5. Nhấp vào trình đơn thả xuống Thêm khoá, sau đó chọn Tạo khoá mới.

  6. Chọn JSON làm Loại khoá rồi nhấp vào Tạo.

  7. Đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn của tệp JSON.

Linux hoặc macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Ứng dụng web

  1. Mở trang Thông tin xác thực của Google API Console.

  2. Nếu được nhắc, hãy chọn dự án mà bạn đã bật API Ad Manager.

  3. Trên trang Thông tin xác thực, hãy chọn Tạo thông tin xác thực, sau đó chọn Mã ứng dụng khách OAuth.

  4. Chọn loại ứng dụng Ứng dụng web.

  5. Điền thông tin vào biểu mẫu rồi nhấp vào Tạo. Các ứng dụng sử dụng ngôn ngữ và khung như PHP, Java, Python, Ruby và .NET phải chỉ định URI chuyển hướng được uỷ quyền. URI chuyển hướng là các điểm cuối mà máy chủ OAuth 2.0 có thể gửi phản hồi. Các điểm cuối này phải tuân thủ quy tắc xác thực của Google.

  6. Sau khi tạo thông tin xác thực, hãy tải tệp client_secret.json xuống. Lưu trữ tệp một cách an toàn ở một vị trí mà chỉ ứng dụng của bạn mới có thể truy cập.

Từ đây, hãy làm theo các bước để lấy mã truy cập OAuth 2.0

Phát triển tại địa phương

Thiết lập Thông tin xác thực mặc định của ứng dụng (ADC) trong môi trường cục bộ.

Cài đặt Google Cloud CLI, sau đó khởi động bằng cách chạy lệnh sau:

gcloud init

Tạo thông tin xác thực cục bộ cho Tài khoản Google của bạn và đặt mã dự án thành một dự án đã bật API Ad Manager:

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/admanager"
gcloud auth application-default set-quota-project PROJECT_ID

Ngoài ra, hãy xác thực dưới dạng Tài khoản dịch vụ bằng cách đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn của tệp khoá.

Linux hoặc macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Định cấu hình mạng Ad Manager

Tài khoản dịch vụ

  1. Chuyển đến mạng Ad Manager của bạn.
  2. Nhấp vào thẻ Quản trị.
  3. Đảm bảo rằng bạn đã bật Quyền truy cập API.
  4. Nhấp vào nút Thêm người dùng tài khoản dịch vụ.
  5. Điền vào biểu mẫu bằng email của tài khoản dịch vụ. Bạn phải thêm người dùng tài khoản dịch vụ vào các vai trò và nhóm phù hợp để tích hợp API.
  6. Nhấp vào nút Lưu. Một thông báo sẽ xuất hiện để xác nhận việc thêm tài khoản dịch vụ của bạn.
  7. Xem người dùng tài khoản dịch vụ hiện có bằng cách chuyển đến thẻ Người dùng rồi nhấp vào bộ lọc Tài khoản dịch vụ.

Ứng dụng web

  1. Chuyển đến mạng Ad Manager của bạn.
  2. Nhấp vào thẻ Quản trị.
  3. Đảm bảo rằng bạn đã bật Quyền truy cập API.

Phát triển cục bộ

  1. Chuyển đến mạng Ad Manager của bạn.
  2. Nhấp vào thẻ Quản trị.
  3. Đảm bảo rằng bạn đã bật Quyền truy cập API.

Không có thư viện ứng dụng

Nếu không sử dụng thư viện ứng dụng, bạn vẫn nên sử dụng thư viện OAuth2 để xác thực.

Để biết hướng dẫn chi tiết về cách lấy mã truy cập, hãy xem bài viết Sử dụng OAuth2 với API của Google.

Mã truy cập

Đưa mã truy cập vào yêu cầu gửi đến API bằng cách thêm tham số truy vấn access_token hoặc giá trị tiêu đề HTTP Authorization Bearer. Nếu có thể, bạn nên sử dụng tiêu đề HTTP vì chuỗi truy vấn có xu hướng hiển thị trong nhật ký máy chủ.

Ví dụ:

GET /v1/networks/1234
Host: admanager.googleapis.com
Authorization: Bearer ya29.a0Ad52N3_shYLX

GET https://admanager.googleapis.com/v1/networks/1234?access_token=1/fFAGRNJru1FTz70BzhT3Zg

Phạm vi

Mỗi mã truy cập được liên kết với một hoặc nhiều phạm vi. Phạm vi kiểm soát tập hợp tài nguyên và hoạt động mà mã truy cập cho phép. API Ad Manager có hai phạm vi. Bạn nên sử dụng phạm vi admanager.readonly hẹp hơn nếu ứng dụng của bạn không cần ghi dữ liệu.

Phạm vi Quyền
https://www.googleapis.com/auth/admanager Xem và quản lý các chiến dịch của bạn trên Google Ad Manager.
https://www.googleapis.com/auth/admanager.readonly Xem các chiến dịch và dữ liệu của bạn trên Google Ad Manager.