Tài liệu này giải thích cách triển khai tính năng uỷ quyền OAuth 2.0 để truy cập vào YouTube Analytics API hoặc YouTube Reporting API từ một ứng dụng web JavaScript. OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với một ứng dụng trong khi vẫn bảo mật tên người dùng, mật khẩu và các thông tin khác. Ví dụ: Một ứng dụng có thể sử dụng OAuth 2.0 để có quyền truy xuất dữ liệu YouTube Analytics của một kênh.
Quy trình OAuth 2.0 này được gọi là quy trình cấp quyền ngầm ẩn. API này được thiết kế cho các ứng dụng chỉ truy cập vào API khi người dùng có mặt ở ứng dụng. Những ứng dụng này không thể lưu trữ thông tin mật.
Trong quy trình này, ứng dụng của bạn sẽ mở một URL của Google sử dụng các tham số truy vấn để xác định ứng dụng của bạn và loại quyền truy cập vào API mà ứng dụng yêu cầu. Bạn có thể mở URL trong cửa sổ trình duyệt hiện tại hoặc cửa sổ bật lên. Người dùng có thể xác thực với Google và cấp các quyền được yêu cầu. Sau đó, Google sẽ chuyển hướng người dùng quay lại ứng dụng của bạn. Lệnh chuyển hướng này bao gồm mã truy cập mà ứng dụng của bạn sẽ xác minh rồi sử dụng để tạo yêu cầu API.
Thư viện ứng dụng API của Google và Dịch vụ nhận dạng của Google
Nếu sử dụng Thư viện ứng dụng API Google dành cho JavaScript để thực hiện các lệnh gọi được uỷ quyền đến Google, thì bạn nên sử dụng thư viện JavaScript Dịch vụ nhận dạng của Google để xử lý quy trình OAuth 2.0. Vui lòng xem mô hình mã thông báo của Dịch vụ nhận dạng của Google. Mô hình này dựa trên quy trình cấp quyền ngầm của OAuth 2.0.
Điều kiện tiên quyết
Bật API cho dự án của bạn
Mọi ứng dụng gọi API của Google đều cần bật các API đó trong API Console.
Cách bật API cho dự án:
- Open the API Library trong Google API Console.
- If prompted, select a project, or create a new one.
- Sử dụng trang Thư viện để tìm và bật API YouTube Analytics và API Báo cáo của YouTube. Nhiều ứng dụng truy xuất dữ liệu YouTube Analytics cũng tương thích với YouTube Data API. Tìm mọi API khác mà ứng dụng của bạn sẽ sử dụng và bật các API đó.
Tạo thông tin xác thực cho phép
Mọi ứng dụng dùng OAuth 2.0 để truy cập API Google đều phải có thông tin xác thực uỷ quyền giúp xác định ứng dụng đó cho máy chủ OAuth 2.0 của Google. Các bước sau đây sẽ giải thích cách tạo thông tin xác thực cho dự án của bạn. Sau đó, ứng dụng của bạn có thể sử dụng thông tin xác thực để truy cập vào các API mà bạn đã bật cho dự án đó.
- Go to the Credentials page.
- Nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth.
- Chọn loại ứng dụng Web application (Ứng dụng web).
- Hoàn thành biểu mẫu. Những ứng dụng dùng JavaScript để đưa ra các yêu cầu API được uỷ quyền của Google phải chỉ định các nguồn gốc JavaScript được phép. Các nguồn gốc xác định những miền mà từ đó ứng dụng của bạn có thể gửi yêu cầu đến máy chủ OAuth 2.0. Những nguồn gốc này phải tuân thủ các quy tắc xác thực của Google.
Xác định phạm vi truy cập
Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào các tài nguyên mà ứng dụng cần, đồng thời cho phép người dùng kiểm soát lượng quyền truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có thể có mối quan hệ nghịch đảo giữa số phạm vi được yêu cầu và khả năng có được sự đồng ý của người dùng.
Trước khi bắt đầu triển khai việc uỷ quyền OAuth 2.0, bạn nên xác định các phạm vi mà ứng dụng của bạn sẽ cần có quyền truy cập.
API YouTube Analytics sử dụng các phạm vi sau:
| Phạm vi | |
|---|---|
| https://www.googleapis.com/auth/youtube | Quản lý tài khoản YouTube của bạn |
| https://www.googleapis.com/auth/youtube.readonly | Xem tài khoản YouTube của bạn |
| https://www.googleapis.com/auth/youtubepartner | Xem và quản lý nội dung cũng như nội dung liên quan của bạn trên YouTube |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Xem báo cáo YouTube Analytics bằng tiền và phi tiền tệ cho nội dung YouTube của bạn |
| https://www.googleapis.com/auth/yt-analytics.readonly | Xem báo cáo YouTube Analytics cho nội dung YouTube của bạn |
API Báo cáo của YouTube sử dụng các phạm vi sau:
| Phạm vi | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Xem báo cáo YouTube Analytics bằng tiền và phi tiền tệ cho nội dung YouTube của bạn |
| https://www.googleapis.com/auth/yt-analytics.readonly | Xem báo cáo YouTube Analytics cho nội dung YouTube của bạn |
Tài liệu về Phạm vi API của OAuth 2.0 chứa danh sách đầy đủ các phạm vi mà bạn có thể dùng để truy cập vào các API của Google.
Lấy mã truy cập OAuth 2.0
Các bước sau đây cho biết cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để có được sự đồng ý của người dùng nhằm thay mặt người dùng thực hiện yêu cầu API. Ứng dụng của bạn phải nhận được sự đồng ý đó thì mới có thể thực thi yêu cầu API của Google mà cần phải có sự cho phép của người dùng.
Bước 1: Chuyển hướng tới máy chủ OAuth 2.0 của Google
Để yêu cầu quyền truy cập vào dữ liệu của người dùng, hãy chuyển hướng người dùng đến máy chủ OAuth 2.0 của Google.
Điểm cuối OAuth 2.0
Tạo một URL để yêu cầu quyền truy cập từ điểm cuối OAuth 2.0 của Google tại https://accounts.google.com/o/oauth2/v2/auth. Có thể truy cập vào điểm cuối này qua HTTPS; các kết nối HTTP thuần tuý bị từ chối.
Máy chủ uỷ quyền của Google hỗ trợ các tham số chuỗi truy vấn sau đây cho các ứng dụng máy chủ web:
| Thông số | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Bắt buộc
Mã ứng dụng khách cho ứng dụng của bạn. Bạn có thể tìm thấy giá trị này trong API Console Credentials page. |
||||||||||||||||||
redirect_uri |
Bắt buộc
Xác định nơi máy chủ API chuyển hướng người dùng sau khi người dùng hoàn tất quy trình uỷ quyền. Giá trị này phải khớp chính xác với một trong các URI chuyển hướng được uỷ quyền cho ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong API Console
Credentials pagecủa ứng dụng. Nếu giá trị này không khớp với một URI chuyển hướng được uỷ quyền cho Xin lưu ý rằng giao thức |
||||||||||||||||||
response_type |
Bắt buộc
Các ứng dụng JavaScript cần đặt giá trị của thông số thành |
||||||||||||||||||
scope |
Bắt buộc
Danh sách phạm vi, phân tách bằng dấu cách giúp xác định các tài nguyên mà ứng dụng của bạn có thể truy cập thay mặt người dùng. Các giá trị này cho người dùng biết màn hình xin phép mà Google sẽ hiển thị cho người dùng. Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào các tài nguyên mà ứng dụng cần trong khi vẫn cho phép người dùng kiểm soát lượng quyền truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có mối quan hệ nghịch đảo giữa số phạm vi được yêu cầu và khả năng có được sự đồng ý của người dùng. API YouTube Analytics sử dụng các phạm vi sau:
API Báo cáo của YouTube sử dụng các phạm vi sau:
Tài liệu về Phạm vi API của OAuth 2.0 cung cấp danh sách đầy đủ các phạm vi mà bạn có thể dùng để truy cập vào API của Google. Ứng dụng của bạn nên yêu cầu quyền truy cập vào phạm vi uỷ quyền theo ngữ cảnh bất cứ khi nào có thể. Khi yêu cầu quyền truy cập vào dữ liệu người dùng theo ngữ cảnh, thông qua tính năng uỷ quyền tăng dần, bạn giúp người dùng dễ dàng hiểu được lý do ứng dụng của bạn cần quyền truy cập mà ứng dụng đang yêu cầu. |
||||||||||||||||||
state |
Recommended (Nên dùng)
Chỉ định bất kỳ giá trị chuỗi nào mà ứng dụng của bạn sử dụng để duy trì trạng thái giữa yêu cầu uỷ quyền và phản hồi của máy chủ uỷ quyền.
Máy chủ sẽ trả về giá trị chính xác mà bạn gửi dưới dạng cặp Bạn có thể sử dụng tham số này cho một số mục đích, chẳng hạn như hướng người dùng đến đúng tài nguyên trong ứng dụng của bạn, gửi số chỉ dùng một lần và giảm thiểu việc giả mạo yêu cầu trên nhiều trang web. Vì có thể đoán được |
||||||||||||||||||
include_granted_scopes |
Không bắt buộc
Cho phép các ứng dụng dùng chế độ uỷ quyền gia tăng để yêu cầu quyền truy cập vào các phạm vi khác theo bối cảnh. Nếu bạn đặt giá trị của thông số này thành |
||||||||||||||||||
enable_granular_consent |
Không bắt buộc
Giá trị mặc định là Khi Google bật các quyền chi tiết cho một ứng dụng, tham số này sẽ không còn hiệu lực nữa. |
||||||||||||||||||
login_hint |
Không bắt buộc
Nếu biết người dùng nào đang cố gắng xác thực, thì ứng dụng của bạn có thể sử dụng thông số này để cung cấp gợi ý cho Máy chủ xác thực của Google. Máy chủ sử dụng gợi ý để đơn giản hoá quy trình đăng nhập bằng cách điền sẵn trường email trong biểu mẫu đăng nhập hoặc chọn phiên đăng nhập nhiều tài khoản thích hợp. Đặt giá trị thông số thành một địa chỉ email hoặc giá trị nhận dạng |
||||||||||||||||||
prompt |
Không bắt buộc
Danh sách câu lệnh, phân tách bằng dấu cách, phân biệt chữ hoa chữ thường để trình bày cho người dùng. Nếu bạn không chỉ định tham số này, người dùng sẽ chỉ được nhắc vào lần đầu tiên dự án của bạn yêu cầu quyền truy cập. Hãy xem bài viết Nhắc lại sự đồng ý để biết thêm thông tin. Các giá trị có thể là:
|
||||||||||||||||||
Mẫu chuyển hướng đến máy chủ uỷ quyền của Google
URL mẫu bên dưới yêu cầu quyền truy cập ngoại tuyến
(access_type=offline) đến một phạm vi cho phép truy cập để truy xuất
báo cáo YouTube Analytics của người dùng. Phương thức này sử dụng tính năng uỷ quyền gia tăng để đảm bảo rằng mã truy cập mới bao gồm mọi phạm vi mà trước đây người dùng đã cấp quyền truy cập cho ứng dụng. URL này cũng đặt giá trị cho các tham số redirect_uri, response_type và client_id bắt buộc, cũng như cho tham số state. URL chứa dấu ngắt dòng và dấu cách để dễ đọc.
https://accounts.google.com/o/oauth2/v2/auth?
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
include_granted_scopes=true&
state=state_parameter_passthrough_value&
redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
response_type=token&
client_id=client_id
Sau khi bạn tạo URL yêu cầu, hãy chuyển hướng người dùng đến URL đó.
Mã mẫu JavaScript
Đoạn mã JavaScript sau đây cho biết cách bắt đầu quy trình uỷ quyền trong JavaScript mà không cần sử dụng Thư viện ứng dụng API của Google cho JavaScript. Vì điểm cuối OAuth 2.0 này không hỗ trợ tính năng Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), nên đoạn mã sẽ tạo một biểu mẫu để mở yêu cầu đến điểm cuối đó.
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauthSignIn() {
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create <form> element to submit parameters to OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': 'YOUR_CLIENT_ID',
'redirect_uri': 'YOUR_REDIRECT_URI',
'response_type': 'token',
'scope': 'https://www.googleapis.com/auth/yt-analytics.readonly',
'include_granted_scopes': 'true',
'state': 'pass-through value'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
Bước 2: Google nhắc người dùng đồng ý
Ở bước này, người dùng sẽ quyết định xem có cấp cho ứng dụng của bạn quyền truy cập mà bạn yêu cầu hay không. Ở giai đoạn này, Google sẽ hiển thị một cửa sổ đồng ý cho biết tên ứng dụng của bạn và các dịch vụ API của Google mà Google đang yêu cầu cấp quyền truy cập bằng thông tin xác thực uỷ quyền của người dùng và thông tin tóm tắt về phạm vi truy cập được cấp. Sau đó, người dùng có thể đồng ý cấp quyền truy cập vào một hoặc nhiều phạm vi mà ứng dụng của bạn yêu cầu hoặc từ chối yêu cầu đó.
Ứng dụng của bạn không cần làm gì ở giai đoạn này vì đang chờ phản hồi từ máy chủ OAuth 2.0 của Google cho biết liệu đã được cấp quyền truy cập nào hay chưa. Phản hồi đó được giải thích trong bước sau.
Lỗi
Các yêu cầu gửi đến điểm cuối uỷ quyền OAuth 2.0 của Google có thể hiển thị thông báo lỗi dành cho người dùng thay vì các quy trình xác thực và uỷ quyền như dự kiến. Dưới đây là danh sách các mã lỗi phổ biến và cách giải quyết nên dùng.
admin_policy_enforced
Tài khoản Google này không thể cấp quyền cho một hoặc nhiều phạm vi đã yêu cầu do các chính sách của quản trị viên Google Workspace của họ. Hãy xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát những ứng dụng nội bộ và ứng dụng bên thứ ba nào truy cập vào dữ liệu trong Google Workspace để biết thêm thông tin về cách quản trị viên có thể hạn chế quyền truy cập vào tất cả phạm vi hoặc các phạm vi nhạy cảm và bị hạn chế cho đến khi bạn cấp quyền truy cập rõ ràng cho mã ứng dụng khách OAuth.
disallowed_useragent
Điểm cuối uỷ quyền hiển thị trong một tác nhân người dùng được nhúng theo Chính sách của OAuth 2.0 mà Google không cho phép.
Android
Nhà phát triển Android có thể gặp phải thông báo lỗi này khi mở các yêu cầu uỷ quyền trong android.webkit.WebView.
Thay vào đó, nhà phát triển nên sử dụng các thư viện Android, chẳng hạn như
Đăng nhập bằng Google cho Android hoặc
AppAuth cho Android của OpenID Foundation.
Các nhà phát triển web có thể gặp phải lỗi này khi một ứng dụng Android mở một đường liên kết web chung trong một tác nhân người dùng được nhúng và người dùng chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ trang web của bạn. Nhà phát triển nên cho phép các đường liên kết chung mở trong trình xử lý đường liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Đường liên kết trong ứng dụng Android hoặc ứng dụng trình duyệt mặc định. Thư viện Thẻ tuỳ chỉnh Android cũng là một lựa chọn được hỗ trợ.
iOS
Nhà phát triển iOS và macOS có thể gặp lỗi này khi mở các yêu cầu uỷ quyền trong WKWebView.
Thay vào đó, nhà phát triển nên sử dụng các thư viện iOS, chẳng hạn như
Đăng nhập bằng Google cho iOS hoặc
AppAuth cho iOS của OpenID Foundation.
Các nhà phát triển web có thể gặp phải lỗi này khi ứng dụng iOS hoặc macOS mở một đường liên kết web chung trong một tác nhân người dùng được nhúng và người dùng chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ trang web của bạn. Nhà phát triển phải cho phép các đường liên kết chung mở trong trình xử lý đường liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Đường liên kết phổ quát hoặc ứng dụng trình duyệt mặc định. Thư viện SFSafariViewController cũng là một lựa chọn được hỗ trợ.
org_internal
Mã ứng dụng khách OAuth trong yêu cầu này thuộc một dự án giới hạn quyền truy cập vào Tài khoản Google trong một Tổ chức Google Cloud cụ thể. Để biết thêm thông tin về tuỳ chọn cấu hình này, hãy xem mục Loại người dùng trong bài viết trợ giúp về Thiết lập màn hình xin phép bằng OAuth.
invalid_client
Nguồn gốc mà yêu cầu được thực hiện không được phép đối với ứng dụng này. Hãy xem origin_mismatch.
invalid_grant
Khi sử dụng chức năng uỷ quyền gia tăng, mã thông báo có thể đã hết hạn hoặc đã hết hiệu lực. Xác thực người dùng một lần nữa và yêu cầu người dùng đồng ý để lấy mã thông báo mới. Nếu bạn vẫn gặp lỗi này, hãy đảm bảo rằng ứng dụng của bạn đã được định cấu hình đúng cách cũng như bạn đang sử dụng đúng mã thông báo và tham số trong yêu cầu của mình. Nếu không, tài khoản người dùng đó có thể đã bị xoá hoặc vô hiệu hoá.
origin_mismatch
Lược đồ, miền và/hoặc cổng của JavaScript khởi tạo yêu cầu uỷ quyền có thể không khớp với URI gốc JavaScript được uỷ quyền đã đăng ký cho mã ứng dụng khách OAuth. Xem lại các nguồn gốc JavaScript được cho phép trong Google API Console Credentials page.
redirect_uri_mismatch
redirect_uri được truyền trong yêu cầu uỷ quyền không khớp với URI chuyển hướng được uỷ quyền cho mã ứng dụng OAuth. Xem lại các URI chuyển hướng được uỷ quyền trong Google API Console Credentials page.
Lược đồ, miền và/hoặc cổng của JavaScript khởi tạo yêu cầu uỷ quyền có thể không khớp với URI gốc JavaScript được uỷ quyền đã đăng ký cho mã ứng dụng khách OAuth. Xem lại các nguồn gốc JavaScript được cho phép trong Google API Console Credentials page.
Tham số redirect_uri có thể tham chiếu đến quy trình OAuth ngoài băng tần (OOB) đã ngừng hoạt động và không còn được hỗ trợ. Hãy tham khảo
hướng dẫn di chuyển để cập nhật
chế độ tích hợp của bạn.
invalid_request
Đã xảy ra lỗi với yêu cầu của bạn. Điều này có thể là do một số lý do:
- Yêu cầu không được định dạng đúng
- Yêu cầu thiếu thông số bắt buộc
- Yêu cầu này sử dụng một phương thức uỷ quyền mà Google không hỗ trợ. Xác minh việc tích hợp OAuth của bạn bằng phương thức tích hợp được đề xuất
Bước 3: Xử lý phản hồi của máy chủ OAuth 2.0
Điểm cuối OAuth 2.0
Máy chủ OAuth 2.0 gửi phản hồi tới redirect_uri được chỉ định trong yêu cầu về mã truy cập.
Nếu người dùng phê duyệt yêu cầu, thì phản hồi sẽ chứa mã truy cập. Nếu người dùng không phê duyệt yêu cầu, thì phản hồi sẽ chứa thông báo lỗi. Mã truy cập hoặc thông báo lỗi sẽ được trả về trên mảnh băm của URI chuyển hướng, như minh hoạ dưới đây:
Phản hồi về mã truy cập:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Ngoài tham số
access_token, chuỗi mảnh cũng chứa tham sốtoken_type(luôn được đặt thànhBearer) và tham sốexpires_inchỉ định thời gian tồn tại của mã thông báo (tính bằng giây). Nếu tham sốstateđược chỉ định trong yêu cầu mã truy cập, thì giá trị của tham số đó cũng được đưa vào phản hồi.- Phản hồi lỗi:
https://oauth2.example.com/callback#error=access_denied
Phản hồi mẫu của máy chủ OAuth 2.0
Bạn có thể kiểm thử quy trình này bằng cách nhấp vào URL mẫu sau đây. URL này yêu cầu quyền chỉ có thể đọc để xem siêu dữ liệu của các tệp trong Google Drive:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& include_granted_scopes=true& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& response_type=token& client_id=client_id
Sau khi hoàn tất quy trình OAuth 2.0, bạn sẽ được chuyển hướng đến
http://localhost/oauth2callback. URL đó sẽ báo lỗi 404 NOT FOUND trừ phi máy cục bộ của bạn tình cờ phân phát tệp tại địa chỉ đó. Bước tiếp theo cung cấp thêm thông tin chi tiết về thông tin được trả về trong URI khi người dùng được chuyển hướng quay lại ứng dụng của bạn.
Gọi API của Google
Điểm cuối OAuth 2.0
Sau khi ứng dụng nhận được mã truy cập, bạn có thể dùng mã này để thực hiện lệnh gọi đến API của Google thay mặt cho một tài khoản người dùng cụ thể nếu(các) phạm vi quyền truy cập mà API đó yêu cầu đã được cấp. Để thực hiện việc này, hãy đư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ị Bearer của tiêu đề HTTP Authorization. Nếu có thể, bạn nên ưu tiên sử dụng tiêu đề HTTP vì chuỗi truy vấn thường xuất hiện trong nhật ký máy chủ. Trong hầu hết
trường hợp, bạn có thể sử dụng thư viện ứng dụng để thiết lập lệnh gọi đến API của Google (ví dụ: khi
gọi API YouTube Analytics).
Xin lưu ý rằng API YouTube Analytics không hỗ trợ quy trình cho tài khoản dịch vụ. YouTube Reporting API chỉ hỗ trợ tài khoản dịch vụ cho những chủ sở hữu nội dung trên YouTube sở hữu và quản lý nhiều kênh YouTube, chẳng hạn như hãng thu âm và hãng phim.
Bạn có thể dùng thử tất cả các API của Google và xem các phạm vi của các API đó trong Sân chơi OAuth 2.0.
Ví dụ về HTTP GET
Lệnh gọi đến điểm cuối
reports.query (API YouTube Analytics) sử dụng tiêu đề HTTP Authorization: Bearer
có thể có dạng như sau. Xin lưu ý rằng bạn cần chỉ định mã truy cập của riêng mình:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Sau đây là lệnh gọi đến cùng một API cho người dùng đã được xác thực bằng cách sử dụng tham số chuỗi truy vấn access_token:
GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Ví dụ về curl
Bạn có thể kiểm thử các lệnh này bằng ứng dụng dòng lệnh curl. Dưới đây là ví dụ về cách sử dụng tuỳ chọn tiêu đề HTTP (ưu tiên):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Hoặc, một cách khác là tuỳ chọn tham số chuỗi truy vấn:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Mã mẫu JavaScript
Đoạn mã dưới đây minh hoạ cách sử dụng CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc) để gửi yêu cầu đến một API của Google. Ví dụ này không sử dụng Thư viện ứng dụng API của Google cho JavaScript. Tuy nhiên, ngay cả khi bạn không sử dụng thư viện ứng dụng, hướng dẫn hỗ trợ CORS (Chia sẻ tài nguyên giữa nhiều nguồn gốc) trong tài liệu của thư viện đó có thể sẽ giúp bạn hiểu rõ hơn về các yêu cầu này.
Trong đoạn mã này, biến access_token đại diện cho mã thông báo mà bạn nhận được để thay mặt người dùng được uỷ quyền gửi yêu cầu API. Ví dụ hoàn chỉnh minh hoạ cách lưu trữ mã thông báo đó trong bộ nhớ cục bộ của trình duyệt và truy xuất mã khi tạo yêu cầu API.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
console.log(xhr.response);
};
xhr.send(null);
Ví dụ đầy đủ
Điểm cuối OAuth 2.0
Mã mẫu này minh hoạ cách hoàn tất quy trình OAuth 2.0 trong JavaScript mà không cần sử dụng Thư viện ứng dụng API của Google cho JavaScript. Mã này dành cho một trang HTML hiển thị nút để thử yêu cầu API. Nếu bạn nhấp vào nút này, đoạn mã sẽ kiểm tra xem trang đã lưu trữ mã truy cập API trong bộ nhớ cục bộ của trình duyệt hay chưa. Nếu có thì lệnh này sẽ thực thi yêu cầu API. Nếu không, thao tác này sẽ bắt đầu quy trình OAuth 2.0.
Đối với quy trình OAuth 2.0, trang sẽ làm theo các bước sau:
- Thao tác này chuyển người dùng đến máy chủ OAuth 2.0 của Google. Máy chủ này yêu cầu quyền truy cập vào phạm vi
https://www.googleapis.com/auth/yt-analytics.readonly. - Sau khi cấp (hoặc từ chối) quyền truy cập vào một hoặc nhiều phạm vi được yêu cầu, người dùng sẽ được chuyển hướng đến trang gốc. Trang này sẽ phân tích cú pháp mã truy cập từ chuỗi giá trị nhận dạng mảnh.
Trang sử dụng mã truy cập để tạo yêu cầu API mẫu.
Yêu cầu API này gọi phương thức
reports.querycủa API YouTube Analytics để truy xuất số lượt xem cho kênh YouTube của người dùng được uỷ quyền.- Nếu yêu cầu được thực thi thành công, thì phản hồi của API sẽ được ghi vào bảng điều khiển gỡ lỗi của trình duyệt.
Bạn có thể thu hồi quyền truy cập vào ứng dụng đó thông qua trang Quyền đối với Tài khoản Google của mình. Ứng dụng sẽ được liệt kê là Bản minh hoạ OAuth 2.0 cho Tài liệu API của Google.
Để chạy mã này trên máy, bạn cần đặt các giá trị cho các biến YOUR_CLIENT_ID và YOUR_REDIRECT_URI tương ứng với thông tin xác thực uỷ quyền của bạn. Bạn phải đặt biến YOUR_REDIRECT_URI thành cùng một URL nơi trang được phân phát. Giá trị này phải khớp chính xác với một trong các URI chuyển hướng được uỷ quyền cho ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong API Console Credentials page. Nếu giá trị này không khớp với một URI được uỷ quyền, bạn sẽ gặp lỗi redirect_uri_mismatch. Dự án của bạn cũng phải bật API thích hợp cho yêu cầu này.
<html><head></head><body>
<script>
var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
// Parse query string to see if page request is coming from OAuth 2.0 server.
var fragmentString = location.hash.substring(1);
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0 && params['state']) {
if (params['state'] == localStorage.getItem('state')) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
trySampleRequest();
} else {
console.log('State mismatch. Possible CSRF attack');
}
}
// Function to generate a random state value
function generateCryptoRandomState() {
const randomValues = new Uint32Array(2);
window.crypto.getRandomValues(randomValues);
// Encode as UTF-8
const utf8Encoder = new TextEncoder();
const utf8Array = utf8Encoder.encode(
String.fromCharCode.apply(null, randomValues)
);
// Base64 encode the UTF-8 data
return btoa(String.fromCharCode.apply(null, utf8Array))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// If there's an access token, try an API request.
// Otherwise, start OAuth 2.0 flow.
function trySampleRequest() {
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
if (params && params['access_token']) {
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
if (xhr.readyState === 4 && xhr.status === 200) {
console.log(xhr.response);
} else if (xhr.readyState === 4 && xhr.status === 401) {
// Token invalid, so prompt for user permission.
oauth2SignIn();
}
};
xhr.send(null);
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// create random state value and store in local storage
var state = generateCryptoRandomState();
localStorage.setItem('state', state);
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create element to open OAuth 2.0 endpoint in new window.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': YOUR_CLIENT_ID,
'redirect_uri': YOUR_REDIRECT_URI,
'scope': 'https://www.googleapis.com/auth/yt-analytics.readonly',
'state': state,
'include_granted_scopes': 'true',
'response_type': 'token'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
</script>
<button onclick="trySampleRequest();">Try sample request</button>
</body></html>
Quy tắc xác thực nguồn gốc JavaScript
Google áp dụng các quy tắc xác thực sau đây cho các nguồn gốc JavaScript để giúp nhà phát triển đảm bảo an toàn cho ứng dụng của họ. Nguồn gốc JavaScript của bạn phải tuân thủ các quy tắc này. Xem phần 3 của RFC 3986 để biết định nghĩa về miền, máy chủ lưu trữ và giao thức, được đề cập bên dưới.
| Các quy tắc xác thực | |
|---|---|
| Lược đồ |
Nguồn gốc JavaScript phải sử dụng giao thức HTTPS, không phải HTTP thuần tuý. Các URI của máy chủ cục bộ (bao gồm cả URI địa chỉ IP của máy chủ cục bộ) được miễn quy tắc này. |
| Máy chủ lưu trữ |
Máy chủ không được là địa chỉ IP thô. Địa chỉ IP của máy chủ cục bộ được miễn tuân theo quy tắc này. |
| Miền |
“googleusercontent.com”.goo.gl) trừ phi ứng dụng sở hữu miền đó. |
| Thông tin người dùng |
Nguồn gốc JavaScript không được chứa thành phần phụ thông tin người dùng. |
| Đường dẫn |
Nguồn gốc JavaScript không được chứa thành phần đường dẫn. |
| Cụm từ tìm kiếm |
Nguồn gốc JavaScript không được chứa thành phần truy vấn. |
| Mảnh |
Nguồn gốc JavaScript không được chứa thành phần phân đoạn. |
| Ký tự |
Nguồn gốc JavaScript không được chứa một số ký tự nhất định, bao gồm:
|
Uỷ quyền tăng dần
Trong giao thức OAuth 2.0, ứng dụng của bạn yêu cầu cấp quyền để truy cập vào các tài nguyên được xác định theo phạm vi. Đây được xem là phương pháp mang lại trải nghiệm người dùng tốt nhất để yêu cầu uỷ quyền cho các tài nguyên tại thời điểm bạn cần đến chúng. Để cho phép hoạt động đó, máy chủ uỷ quyền của Google sẽ hỗ trợ uỷ quyền gia tăng. Tính năng này cho phép bạn yêu cầu phạm vi khi cần. Nếu người dùng cấp quyền cho phạm vi mới, tính năng này sẽ trả về mã uỷ quyền có thể đổi lấy mã thông báo chứa tất cả các phạm vi mà người dùng đã cấp cho dự án.
Ví dụ: giả sử một ứng dụng truy xuất báo cáo YouTube Analytics, một số báo cáo trong số đó là báo cáo tiền tệ yêu cầu quyền truy cập vào phạm vi bổ sung không cần thiết cho các báo cáo khác. Trong trường hợp này, tại thời điểm đăng nhập, ứng dụng có thể chỉ yêu cầu quyền truy cập vào phạm vi https://www.googleapis.com/auth/yt-analytics.readonly.
Tuy nhiên, nếu người dùng cố gắng truy xuất một báo cáo tiền tệ, thì ứng dụng cũng có thể yêu cầu quyền truy cập vào phạm vi https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
Các quy tắc sau áp dụng cho mã truy cập có được từ việc uỷ quyền tăng dần:
- Bạn có thể dùng mã thông báo này để truy cập vào các tài nguyên tương ứng với bất kỳ phạm vi nào được đưa vào quy trình uỷ quyền kết hợp mới.
- Khi bạn sử dụng mã làm mới cho hoạt động uỷ quyền kết hợp để lấy mã truy cập, mã truy cập này đại diện cho sự uỷ quyền kết hợp và có thể dùng cho bất kỳ giá trị
scopenào có trong phản hồi. - Hoạt động uỷ quyền kết hợp bao gồm tất cả các phạm vi mà người dùng đã cấp cho dự án API ngay cả khi các ứng dụng khác đã yêu cầu các quyền tài trợ. Ví dụ: nếu một người dùng đã cấp quyền truy cập vào một phạm vi bằng ứng dụng dành cho máy tính của một ứng dụng, sau đó cấp một phạm vi khác cho cùng một ứng dụng đó thông qua một ứng dụng dành cho thiết bị di động, thì quá trình uỷ quyền kết hợp sẽ bao gồm cả hai phạm vi.
- Nếu bạn thu hồi một mã thông báo đại diện cho một lệnh uỷ quyền kết hợp, thì quyền truy cập vào tất cả phạm vi của lệnh uỷ quyền đó thay mặt cho người dùng được liên kết sẽ được thu hồi đồng thời.
Các mã mẫu dưới đây cho biết cách thêm phạm vi vào mã truy cập hiện có. Phương pháp này giúp ứng dụng của bạn tránh phải quản lý nhiều mã truy cập.
Điểm cuối OAuth 2.0
Trong ví dụ này, ứng dụng gọi yêu cầu quyền truy cập để truy xuất dữ liệu YouTube Analytics của người dùng cùng với mọi quyền truy cập khác mà người dùng đã cấp cho ứng dụng.
Để thêm phạm vi vào một mã truy cập hiện có, hãy thêm tham số include_granted_scopes
vào yêu cầu gửi tới máy chủ OAuth 2.0 của Google.
Đoạn mã sau đây minh hoạ cách thực hiện việc này. Đoạn mã này giả định rằng bạn đã lưu trữ những phạm vi mà mã truy cập của bạn hợp lệ trong bộ nhớ cục bộ của trình duyệt. (Mã ví dụ đầy đủ này lưu trữ danh sách các phạm vi mà mã truy cập hợp lệ bằng cách đặt thuộc tính oauth2-test-params.scope trong bộ nhớ cục bộ của trình duyệt.)
Đoạn mã này so sánh các phạm vi mà mã truy cập hợp lệ với phạm vi bạn muốn sử dụng cho một truy vấn cụ thể. Nếu mã truy cập không bao gồm phạm vi đó, thì quy trình OAuth 2.0 sẽ bắt đầu.
Ở đây, hàm oauth2SignIn giống như hàm được cung cấp trong bước 2 (và sẽ được cung cấp ở phần sau trong ví dụ đầy đủ).
var SCOPE = 'https://www.googleapis.com/auth/yt-analytics.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
var scopes = params['scope'].split(' ');
for (var s = 0; s < scopes.length; s++) {
if (SCOPE == scopes[s]) {
current_scope_granted = true;
}
}
}
if (!current_scope_granted) {
oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
// Since you already have access, you can proceed with the API request.
}
Thu hồi mã thông báo
Trong một số trường hợp, người dùng có thể muốn thu hồi quyền truy cập đã cấp cho một ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách chuyển đến phần Cài đặt tài khoản. Hãy xem phần Xoá quyền truy cập của các trang web hoặc ứng dụng trong tài liệu hỗ trợ về những trang web và ứng dụng bên thứ ba có quyền truy cập vào tài khoản của bạn để biết thêm thông tin.
Ứng dụng cũng có thể thu hồi quyền truy cập đã cấp cho ứng dụng theo cách lập trình. Việc thu hồi có lập trình là rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá ứng dụng hoặc tài nguyên API mà ứng dụng yêu cầu đã thay đổi đáng kể. Nói cách khác, một phần trong quy trình xoá có thể bao gồm một yêu cầu API để đảm bảo các quyền đã cấp trước đó cho ứng dụng sẽ bị xoá.
Điểm cuối OAuth 2.0
Để thu hồi mã thông báo theo phương thức lập trình, ứng dụng sẽ gửi yêu cầu đến https://oauth2.googleapis.com/revoke và đưa mã thông báo đó vào dưới dạng thông số:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
Mã này có thể là mã truy cập hoặc mã làm mới. Nếu mã thông báo là mã truy cập và có mã làm mới tương ứng thì mã làm mới cũng sẽ bị thu hồi.
Nếu việc thu hồi được xử lý thành công, thì mã trạng thái HTTP của phản hồi sẽ là 200. Đối với các điều kiện lỗi, một mã trạng thái HTTP 400 sẽ được trả về cùng với một mã lỗi.
Đoạn mã JavaScript sau đây cho biết cách thu hồi mã thông báo trong JavaScript mà không cần sử dụng Thư viện ứng dụng API của Google cho JavaScript. Vì điểm cuối OAuth 2.0 của Google để thu hồi mã thông báo không hỗ trợ tính năng Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), nên mã này sẽ tạo một biểu mẫu và gửi biểu mẫu đến điểm cuối thay vì sử dụng phương thức XMLHttpRequest() để đăng yêu cầu.
function revokeAccess(accessToken) {
// Google's OAuth 2.0 endpoint for revoking access tokens.
var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
// Create <form> element to use to POST data to the OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'post');
form.setAttribute('action', revokeTokenEndpoint);
// Add access token to the form so it is set as value of 'token' parameter.
// This corresponds to the sample curl request, where the URL is:
// https://oauth2.googleapis.com/revoke?token={token}
var tokenField = document.createElement('input');
tokenField.setAttribute('type', 'hidden');
tokenField.setAttribute('name', 'token');
tokenField.setAttribute('value', accessToken);
form.appendChild(tokenField);
// Add form to page and submit it to actually revoke the token.
document.body.appendChild(form);
form.submit();
}