Giới thiệu
Tài liệu này dành cho những nhà phát triển muốn viết thư viện ứng dụng, trình bổ trợ IDE và các công cụ khác để tương tác với các API của Google. Dịch vụ khám phá của các API của Google cho phép bạn thực hiện tất cả những việc trên bằng cách tiết lộ siêu dữ liệu mà máy có thể đọc được về các API khác của Google thông qua một API đơn giản. Hướng dẫn này cung cấp thông tin tổng quan về từng phần trong tài liệu Khám phá cũng như các mẹo hữu ích về cách sử dụng tài liệu.
Tất cả các lệnh gọi đến API đều là các yêu cầu REST, chưa được xác thực, có sử dụng JSON và sử dụng SSL, tức là các URL bắt đầu bằng https.
Nếu chưa hiểu rõ các khái niệm về Dịch vụ khám phá của API Google, bạn nên đọc bài viết Bắt đầu trước khi bắt đầu lập trình.
Định dạng tài liệu khám phá
Phần này cung cấp thông tin tổng quan về tài liệu Khám phá.
Tất cả ví dụ bên dưới đều sử dụng tài liệu Khám phá của Google Cloud Service Management API. Bạn có thể tải tài liệu Khám phá cho API Quản lý dịch vụ đám mây của Google bằng cách thực thi yêu cầu GET này:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1Định dạng của tài liệu Khám phá bao gồm thông tin thuộc 6 danh mục chính:
- Nội dung mô tả cơ bản về API.
- Thông tin Xác thực cho API.
- Chi tiết tài nguyên và giản đồ mô tả dữ liệu của API.
- Thông tin chi tiết về phương thức API.
- Thông tin về mọi tính năng tuỳ chỉnh mà API này hỗ trợ.
- Tài liệu cùng dòng mô tả các thành phần chính của API.
Từng phần trong số các tài liệu khám phá này được mô tả dưới đây. Hãy tham khảo tài liệu Tham khảo để biết thêm thông tin chi tiết về từng tài sản.
Nội dung mô tả API cơ bản
Tài liệu Khám phá chứa tập hợp các thuộc tính dành riêng cho API:
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
Các thuộc tính cấp API này chứa thông tin chi tiết về một phiên bản cụ thể của API, bao gồm cả name, version, title và description. protocol luôn có giá trị cố định là rest vì Dịch vụ khám phá API chỉ hỗ trợ các phương thức RESTful để truy cập vào các API.
Trường servicePath cho biết tiền tố đường dẫn cho phiên bản API cụ thể này.
Xác thực
Phần auth chứa thông tin chi tiết về phạm vi xác thực OAuth 2.0 cho API. Để tìm hiểu thêm về cách sử dụng phạm vi với OAuth 2.0, hãy truy cập vào phần Sử dụng OAuth 2.0 để truy cập vào các API của Google.
Phần auth chứa mục oauth2 và scopes lồng nhau. Phần scopes là mối liên kết khoá/giá trị từ giá trị phạm vi đến thông tin chi tiết về phạm vi đó:
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
Phần auth chỉ xác định phạm vi của một API cụ thể. Để tìm hiểu cách các phạm vi này được liên kết với một phương thức API, hãy tham khảo phần Phương thức dưới đây.
Tài nguyên và lược đồ
Toán tử của API hoạt động trên các đối tượng dữ liệu có tên là resources. Tài liệu về Khám phá được xây dựng dựa trên khái niệm về tài nguyên. Mỗi tài liệu khám phá đều có một phần resources cấp cao nhất để nhóm tất cả tài nguyên được liên kết với API. Ví dụ: API quản lý dịch vụ đám mây của Google có một tài nguyên services và một tài nguyên operations trong resources cấp cao nhất, tài nguyên services có ba tài nguyên phụ là configs, rollouts và consumers:
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
Bên trong mỗi phần tài nguyên là các phương thức được liên kết với tài nguyên đó. Ví dụ: API quản lý dịch vụ đám mây của Google có ba phương thức liên kết với tài nguyên services.rollouts: get, list và create.
Giản đồ cho bạn biết tài nguyên trong API trông như thế nào. Mỗi tài liệu Khám phá có một phần schemas cấp cao nhất, trong đó có chứa một cặp tên/giá trị mã nhận dạng giản đồ cho đối tượng. Mã nhận dạng Schema là duy nhất cho mỗi API và được dùng để xác định duy nhất giản đồ trong mục methods của tài liệu Khám phá:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
Dịch vụ khám phá của API sử dụng JSON Schema nháp-03 để biểu diễn giản đồ. Dưới đây là một đoạn mã của Giản đồ JSON cho tài nguyên Url, cùng với một tài nguyên phản hồi thực tế:
| Giản đồ JSON Tài nguyên phát hành: | Phản hồi tài nguyên phát hành thực tế: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
Các trường được in đậm sẽ cho thấy mối liên kết giữa giản đồ JSON và phản hồi thực tế.
Giản đồ cũng có thể chứa thông tin tham chiếu đến các giản đồ khác. Nếu đang xây dựng một thư viện ứng dụng, bạn có thể lập mô hình hiệu quả các đối tượng của một API trong các lớp mô hình dữ liệu của mình. Trong ví dụ Rollout ở trên, thuộc tính trafficPercentStrategy thực sự là một mã tham chiếu đến giản đồ có mã TrafficPercentStrategy. Nếu xem phần schemas, bạn sẽ thấy giản đồ TrafficPercentStrategy. Bạn có thể thay thế giá trị của giản đồ này cho thuộc tính trafficPercentStrategy trong tài nguyên Rollout (xin lưu ý rằng cú pháp $ref được lấy từ thông số giản đồ JSON).
Các phương thức cũng có thể tham chiếu giản đồ khi cho biết nội dung yêu cầu và phản hồi. Tham khảo mục Phương thức để biết thêm chi tiết.
Phương pháp
Phần cốt lõi của tài liệu khám phá được xây dựng dựa trên các phương pháp. Phương thức là các thao tác có thể thực hiện trên một API. Bạn sẽ tìm thấy phần methods trong nhiều phần của tài liệu Khám phá, kể cả ở cấp cao nhất (chúng tôi gọi là các phương thức cấp API) hoặc ở cấp resources.
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
Mặc dù API có thể có các phương thức cấp API, nhưng tài nguyên phải có phần methods.
Mỗi phần methods là một bản đồ khoá/giá trị từ tên phương thức đến các thông tin chi tiết khác về phương thức đó. Ví dụ sau đây minh họa ba phương thức, get, list và create:
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Cuối cùng, mỗi phần của phương thức cung cấp chi tiết các thuộc tính khác nhau về phương thức đó. Sau đây là ví dụ về phương thức get:
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
Phần này chứa thông tin chi tiết chung về phương thức, chẳng hạn như ID riêng để xác định phương thức, httpMethod để sử dụng và path của phương thức (để biết thông tin chi tiết về cách sử dụng thuộc tính path để tính url đầy đủ của phương thức, hãy xem phần Soạn yêu cầu). Ngoài các thuộc tính phương thức chung này, có một số thuộc tính kết nối phương thức này với các phần khác trong tài liệu Khám phá:
Kính ngắm
Phần auth được xác định trước đó trong tài liệu này chứa thông tin về tất cả phạm vi mà một API cụ thể hỗ trợ. Nếu một phương thức hỗ trợ một trong các phạm vi này, thì phương thức sẽ có một mảng phạm vi. Có một mục trong mảng này cho mỗi phạm vi được phương thức này hỗ trợ. Ví dụ: mục scopes của phương thức API quản lý dịch vụ đám mây của Google get có dạng như sau:
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
Lưu ý rằng việc chọn phạm vi xác thực để sử dụng trong ứng dụng của bạn phụ thuộc vào nhiều yếu tố như phương thức nào được gọi và thông số nào được gửi cùng với phương thức. Do đó, nhà phát triển có quyền quyết định phạm vi sử dụng. Chỉ khám phá những tài liệu có phạm vi hợp lệ đối với một phương thức.
Yêu cầu và phản hồi
Nếu phương thức có yêu cầu hoặc nội dung phản hồi, thì các thông tin này sẽ được nêu trong các phần request hoặc response tương ứng. Trong ví dụ get ở trên, phương thức này có phần thân response:
"response": {
"$ref": "Rollout"
}
Cú pháp ở trên cho biết rằng nội dung phản hồi được xác định bởi một giản đồ JSON có mã nhận dạng là Rollout. Bạn có thể tìm thấy giản đồ này trong phần giản đồ cấp cao nhất. Cả nội dung yêu cầu và nội dung phản hồi đều sử dụng cú pháp $ref để tham chiếu đến giản đồ.
Các thông số
Nếu một phương thức có tham số mà người dùng chỉ định, thì các tham số này sẽ được ghi lại trong mục parameters ở cấp phương thức. Phần này chứa bản đồ khóa/giá trị ánh xạ của tên thông số để biết thêm chi tiết về thông số đó:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
Trong ví dụ trên, có hai thông số cho phương thức get:serviceName và rolloutId. Các tham số có thể nằm trong path hoặc URL query; thuộc tính location cho biết vị trí thư viện ứng dụng sẽ đặt tham số.
Có nhiều thuộc tính khác mô tả tham số, bao gồm cả dữ liệu tham số type (hữu ích cho các ngôn ngữ được nhập mạnh). liệu tham số có phải là required hay không và tham số có phải là enum hay không. Hãy tham khảo Hướng dẫn tham khảo để biết thêm thông tin chi tiết về các cơ sở lưu trú.
Thứ tự thông số
Có nhiều cách để thư viện ứng dụng định cấu trúc giao diện của thư viện. Một cách là có một phương thức với mỗi thông số API trong chữ ký phương thức. Tuy nhiên, vì JSON là định dạng không có thứ tự, nên khó có thể biết được cách sắp xếp các thông số trong chữ ký phương thức theo phương thức lập trình. Mảng parameterOrder cung cấp một thứ tự tham số cố định để đưa ra các yêu cầu. Mảng này liệt kê tên của mỗi tham số theo thứ tự mức độ quan trọng; có thể chứa đường dẫn hoặc tham số truy vấn, nhưng mọi tham số trong mảng đều bắt buộc phải có. Trong ví dụ trên, chữ ký phương thức Java có thể có dạng như sau:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);Giá trị đầu tiên trong mảng parameterOrder, serviceName, cũng là phần tử đầu tiên trong chữ ký phương thức. Nếu có các thông số khác trong mảng parameterOrder, các thông số này sẽ nằm sau thông số serviceName. Vì mảng parameterOrder chỉ chứa các tham số bắt buộc, nên tốt nhất là thêm một cách để người dùng chỉ định các tham số không bắt buộc. Ví dụ ở trên thực hiện việc này bằng bản đồ optionalParameters.
Tải nội dung nghe nhìn lên
Nếu một phương thức hỗ trợ việc tải nội dung nghe nhìn lên, chẳng hạn như hình ảnh, âm thanh hoặc video, thì vị trí và giao thức được hỗ trợ để tải nội dung đó lên sẽ được ghi lại trong phần mediaUpload. Phần này chứa thông tin chi tiết về những giao thức tải lên được hỗ trợ và thông tin về những loại nội dung nghe nhìn có thể tải lên:
"supportsMediaUpload": true,
"mediaUpload": {
"accept": [
"image/*"
],
"maxSize": "10MB",
"protocols": {
"simple": {
"multipart": true,
"path": "/upload/storage/v1beta1/b/{bucket}/o"
},
"resumable": {
"multipart": true,
"path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
}
}
}
Trong ví dụ trên, thuộc tính supportsMediaUpload là một giá trị boolean xác định xem phương thức này có hỗ trợ việc tải nội dung nghe nhìn lên hay không. Nếu giá trị là true thì phần mediaUpload sẽ ghi lại các loại phương tiện có thể được tải lên.
Thuộc tính accept là danh sách các phạm vi phương tiện xác định loại MIME được chấp nhận tải lên. Điểm cuối hiển thị trong ví dụ trên sẽ chấp nhận mọi định dạng hình ảnh.
Thuộc tính maxSize có kích thước tối đa của một tệp tải lên. Giá trị là một chuỗi theo đơn vị MB, GB hoặc TB. Trong ví dụ trên, tệp tải lên bị giới hạn ở kích thước tối đa là 10 MB. Xin lưu ý rằng giá trị này không phản ánh hạn mức bộ nhớ còn lại của người dùng cá nhân cho API đó, vì vậy, ngay cả khi quá trình tải lên nhỏ hơn maxSize, thư viện ứng dụng vẫn cần chuẩn bị để xử lý quá trình tải lên không thành công do không đủ dung lượng.
Phần protocols liệt kê các giao thức tải lên mà phương thức hỗ trợ. Giao thức simple chỉ cần POST nội dung nghe nhìn vào điểm cuối đã cho trong một yêu cầu HTTP. Giao thức resumable ngụ ý rằng điểm cuối được cung cấp trong URI path hỗ trợ giao thức tải lên tiếp tục. Nếu thuộc tính multipart là true, điểm cuối chấp nhận nội dung tải lên nhiều phần, có nghĩa là cả yêu cầu JSON và nội dung nghe nhìn có thể được gói cùng nhau trong một phần nội dung biến dạng/liên quan và được gửi cùng nhau. Xin lưu ý rằng cả hai giao thức simple và resumable đều có thể hỗ trợ tải lên nhiều phần.
Thuộc tính path là một mẫu URI và cần được mở rộng giống như thuộc tính path cho phương thức, như nêu trong phần Soạn yêu cầu.
Tải tệp đa phương tiện xuống
Nếu một phương thức hỗ trợ việc tải nội dung xuống, chẳng hạn như hình ảnh, âm thanh hoặc video, thì phương thức đó sẽ được biểu thị bằng thông số supportsMediaDownload:
"supportsMediaDownload": true,
Khi tải nội dung nghe nhìn xuống, bạn phải đặt tham số truy vấn alt thành media trong URL yêu cầu.
Nếu thuộc tính useMediaDownloadService của phương thức API là true, hãy chèn /download trước servicePath để tránh bị chuyển hướng. Ví dụ: đường dẫn tải xuống là /download/youtube/v3/captions/{id} nếu nối servicePath và path là /youtube/v3/captions/{id}. Bạn nên tạo URL tải xuống nội dung nghe nhìn với /download ngay cả khi useMediaDownloadService sai.
Tham số phổ biến
Tài liệu khám phá cấp cao nhất chứa một thuộc tính parameters. Phần này tương tự như phần thông số cho mỗi phương thức, tuy nhiên, các thông số này có thể được áp dụng cho bất kỳ phương thức nào trong API.
Ví dụ: các phương thức get, insert hoặc list của API Google Cloud Service Management có thể có tham số prettyPrint trong các tham số yêu cầu. tham số này sẽ định dạng phản hồi cho tất cả các phương thức đó ở định dạng có thể đọc được. Dưới đây là danh sách các thông số phổ biến:
| Thông số | Ý nghĩa | Lưu ý | Khả năng áp dụng |
|---|---|---|---|
access_token |
Mã thông báo OAuth 2.0 cho người dùng hiện tại. |
|
|
alt |
Định dạng dữ liệu cho phản hồi. |
|
|
callback |
Hàm gọi lại. |
| |
fields |
Bộ chọn chỉ định một số trường để đưa vào nội dung phản hồi. |
|
|
key |
Khóa API. (Bắt buộc*) |
|
|
prettyPrint |
Trả về giá trị nhận dạng và dấu ngắt dòng. |
|
|
quotaUser |
Phương án thay thế cho userIp. |
|
|
userIp |
Địa chỉ IP của người dùng cuối mà cuộc gọi API đang được thực hiện. |
|
Tính năng
Có một số trường hợp API hỗ trợ các tính năng tuỳ chỉnh nằm ngoài phạm vi của phần tài liệu Khám phá còn lại. Các thông tin này được thu thập trong mảng features. Mảng tính năng này chứa một nhãn chuỗi cho mỗi tính năng đặc biệt mà API hỗ trợ. Hiện tại, dataWrapper là tính năng duy nhất được hỗ trợ, nhưng các tính năng khác có thể được hỗ trợ trong tương lai.
"features": dataWrapper
Tính năng dataWrapper cho biết rằng tất cả các yêu cầu và phản hồi từ API đều được gói gọn trong một đối tượng JSON data. Đây là một tính năng của các API Google cũ, nhưng chúng tôi sẽ ngừng sử dụng các tính năng đó trong tương lai. Các API sau đây hỗ trợ tính năng dataWrapper: Moderator v1 và Dịch v2.
Là nhà phát triển thư viện ứng dụng, nếu API hỗ trợ tính năng "dataWrapper", bạn nên làm như sau:
- Trên yêu cầu: Bao bọc tài nguyên yêu cầu trong một đối tượng JSON
data. - Trên phản hồi: Tìm tài nguyên bên trong đối tượng JSON
data.
Các giản đồ trong tài liệu Khám phá không chứa trình bao bọc dữ liệu, vì vậy, bạn phải thêm và xóa chúng một cách rõ ràng. Ví dụ: giả sử có một API có tài nguyên có tên "Foo" có dạng như sau:
{
"id": 1,
"foo": "bar"
}
Trước khi chèn tài nguyên này bằng API, bạn cần bao bọc tài nguyên trong phần tử dữ liệu:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Mặt khác, khi bạn nhận được phản hồi từ API, API đó cũng chứa trình bao bọc dữ liệu:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Để lấy tài nguyên được xác định bởi giản đồ, bạn cần xóa trình bao bọc dữ liệu:
{
"id": 1,
"foo": "bar"
}
Tài liệu cùng dòng
Mỗi tài liệu Khám phá được chú thích bằng một số trường description cung cấp tài liệu cùng dòng cho API. Bạn có thể tìm thấy các trường description của các phần tử API sau đây:
- Bản thân API
- Phạm vi OAuth
- Giản đồ tài nguyên
- Phương thức API
- Tham số phương thức
- Giá trị được chấp nhận cho một số thông số nhất định
Các trường này đặc biệt hữu ích nếu bạn muốn sử dụng Dịch vụ khám phá của API của Google để tạo tài liệu mà con người có thể đọc được cho thư viện ứng dụng, ví dụ: JavaDoc.