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 API của Google. Google APIs Discovery Service cho phép bạn thực hiện tất cả những việc nêu trên bằng cách hiển thị 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 của 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 này.
Tất cả các lệnh gọi đến API đều là các yêu cầu REST dựa trên JSON, chưa được xác thực và sử dụng SSL. Nói cách khác, URL bắt đầu bằng https.
Đị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ả các ví dụ dưới đây đều sử dụng Tài liệu khám phá từ Service Usage API.
Bạn có thể tải Tài liệu khám phá cho Service Usage API bằng cách thực thi yêu cầu GET này:
GET https://serviceusage.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.
- Thông tin chi tiết về tài nguyên và giản đồ mô tả dữ liệu của API.
- Thông tin chi tiết về các phương thức của API.
- Thông tin về mọi tính năng tuỳ chỉnh mà API hỗ trợ.
- Tài liệu nội tuyến mô tả các phần tử chính của API.
Mỗi phần trong tài liệu Khám phá này được mô tả bên dưới.
Nội dung mô tả cơ bản về API
Tài liệu Khám phá chứa một tập hợp các thuộc tính dành riêng cho API. Những thuộc tính này không nhất thiết phải xuất hiện theo thứ tự này hoặc trong cùng một phần của tài liệu khám phá:
"id": "serviceusage:v1", "canonicalName": "Service Usage", "revision": "20240331", "servicePath": "", "baseUrl": "https://serviceusage.googleapis.com/", "kind": "discovery#restDescription", "description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.", "ownerDomain": "google.com", "version_module": true, "version": "v1", "fullyEncodeReservedExpansion": true, "name": "serviceusage", "title": "Service Usage API", "discoveryVersion": "v1", "rootUrl": "https://serviceusage.googleapis.com/", "protocol": "rest"
Các thuộc tính cấp API này bao gồm thông tin chi tiết về một phiên bản cụ thể của API, bao gồm 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 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ề các phạm vi uỷ quyền 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 API Google.
Phần auth chứa phần oauth2 và scopes lồng ghép. Phần scopes là một mối liên kết khoá/giá trị từ giá trị phạm vi đến thông tin chi tiết hơn về phạm vi:
"auth": { "oauth2": { "scopes": { "https://www.googleapis.com/auth/cloud-platform": { "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account." }, "https://www.googleapis.com/auth/cloud-platform.read-only": { "description": "View your data across Google Cloud services and see the email address of your Google Account" }, "https://www.googleapis.com/auth/service.management": { "description": "Manage your Google API service configuration" } } } }
Phần auth chỉ xác định các phạm vi cho 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 bên dưới.
Tài nguyên và giản đồ
Các thao tác 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 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ả các tài nguyên được liên kết với API. Ví dụ: Service Usage API có tài nguyên services và tài nguyên operations trong resources cấp cao nhất:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods 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ụ: Service Usage API có 6 phương thức liên kết với tài nguyên services: get, enable, disable, batchGet, batchEnable và list.
Lược đồ cho bạn biết giao diện của các tài nguyên trong một API. Mỗi tài liệu Khám phá đều có một phần schemas cấp cao nhất, chứa một cặp tên/giá trị của mã nhận dạng giản đồ cho đối tượng. Mã lược đồ là duy nhất cho mỗi API và được dùng để xác định riêng lược đồ trong phần methods của tài liệu Khám phá. Ví dụ: sau đây là một số lược đồ trong tài liệu Discovery của Service Usage API:
"schemas": { "Method": { // JSON schema of the Method resource }, "Authentication": { // JSON schema of the Authentication resource }, "RubySettings": { // JSON schema of the RubySettings resource }, "EnableServiceResponse": { // JSON schema of the EnableServiceResponse resource } }
Dịch vụ Khám phá API sử dụng JSON Schema draft-03 cho các biểu thị giản đồ. Sau đây là một đoạn mã của Giản đồ JSON cho tài nguyên EnableServiceResponse, cùng với GoogleApiServiceusagev1Service mà tài nguyên đó tham chiếu. Cùng với các giản đồ này là một phần của phản hồi thực cho yêu cầu bật API Pub/Sub (pubsub.googleapis.com).
EnableServiceResponse Giản đồ JSON tài nguyên: |
Phản hồi thực tế khi bật một dịch vụ: |
"EnableServiceResponse": { "id": "EnableServiceResponse", "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.", "properties": { "service": { "description": "The new state of the service after enabling.", "$ref": "GoogleApiServiceusageV1Service" } }, "type": "object" }, "GoogleApiServiceusageV1Service": { "description": "A service that is available for use by the consumer.", "properties": { "config": { "$ref": "GoogleApiServiceusageV1ServiceConfig", "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method." }, "name": { "type": "string", "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com" }, " |
"response": { "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse", "service": { "name": "projects/232342569935/services/pubsub.googleapis.com", "config": { "name": "pubsub.googleapis.com", "title": "Cloud Pub/Sub API", "documentation": { "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n" }, "quota": {}, "authentication": {}, "usage": { "requirements": [ "serviceusage.googleapis.com/tos/cloud" ] }, "monitoring": {} }, " |
Các trường được in đậm cho biết mối liên kết giữa JSON Schema và phản hồi thực tế.
Như trong ví dụ này, các giản đồ có thể chứa thông tin tham chiếu đến các giản đồ khác. Nếu bạn đang tạo một thư viện ứng dụng, thì điều này có thể giúp bạn mô hình hoá hiệu quả các đối tượng của một API trong các lớp mô hình dữ liệu. Trong ví dụ EnableServiceResponse ở trên, thuộc tính service là một tham chiếu đến một giản đồ có mã nhận dạng GoogleApiServiceusageV1Service, một giản đồ khác trong tài liệu Khám phá API Mức sử dụng dịch vụ. Bạn có thể thay thế thuộc tính GoogleApiServiceusageV1Service trong tài nguyên EnableServiceResponse bằng giá trị của giản đồ GoogleApiServiceusageV1Service (lưu ý rằng cú pháp $ref bắt nguồn từ quy cách Giản đồ JSON).
Các phương thức cũng có thể tham chiếu đến lược đồ khi cho biết nội dung yêu cầu và phản hồi. Tham khảo phần Phương pháp để biết thêm thông tin chi tiết.
Phương thức
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 thức. Phương thức là các thao tác có thể thực hiện trên một API. Bạn sẽ thấy phần methods ở nhiều khu vực trong tài liệu Khám phá, bao gồm cả ở cấp cao nhất (chúng tôi gọi là 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 khác về phương thức đó. Ví dụ dưới đây minh hoạ 3 phương thức: get, enable và disable:
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
Cuối cùng, phần của mỗi phương thức sẽ trình bày chi tiết nhiều thuộc tính về phương thức đó. Sau đây là một ví dụ về phương thức enable:
"enable": { "path": "v1/{+name}:enable", "request": { "$ref": "EnableServiceRequest" }, "parameterOrder": [ "name" ], "id": "serviceusage.services.enable", "response": { "$ref": "Operation" }, "description": "Enable a service so that it can be used with a project.", "httpMethod": "POST", "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable", "scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/service.management" ], "parameters": { "name": { "location": "path", "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.", "required": true, "type": "string", "pattern": "^[^/]+/[^/]+/services/[^/]+$" } } },
Phần này chứa thông tin chi tiết chung về phương thức, chẳng hạn như ID duy nhất để xác định phương thức, httpMethod cần 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 toán 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òn có một số thuộc tính kết nối phương thức với các phần khác trong tài liệu Khám phá:
Phạm vi
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ả cá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. Mảng này có một mục nhập cho mỗi phạm vi mà phương thức hỗ trợ.
Xin lưu ý rằng việc chọn phạm vi uỷ quyền để sử dụng trong ứng dụng của bạn phụ thuộc vào nhiều yếu tố, chẳng hạn như phương thức nào đang được gọi và những tham số nào được gửi cùng với phương thức đó. Do đó, nhà phát triển sẽ quyết định phạm vi cần sử dụng. Chỉ khám phá những tài liệu có phạm vi hợp lệ cho một phương thức.
Yêu cầu và phản hồi
Nếu phương thức có phần nội dung yêu cầu hoặc phản hồi, thì các phần này sẽ được ghi lại trong các phần request hoặc response tương ứng. Ví dụ: đối với phương thức enable, nội dung của phần request cho biết rằng yêu cầu của phương thức được xác định bằng một giản đồ JSON có mã nhận dạng là EnableServiceRequest. Bạn có thể tìm thấy lược đồ này trong phần lược đồ cấp cao nhất.
Thông số
Nếu một phương thức có các tham số mà người dùng cần chỉ định, thì các tham số này sẽ được ghi lại trong phần parameters ở cấp phương thức. Phần này chứa một mối liên kết khoá/giá trị của tên tham số với thông tin chi tiết hơn về tham số đó.
Ví dụ: có một tham số cho phương thức enable: name.
Các tham số có thể nằm trong path hoặc URL query; thuộc tính location cho biết vị trí mà thư viện ứng dụng nên đặ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ó kiểu dữ liệu mạnh), liệu tham số có phải là required hay không và liệu tham số có phải là một enum hay không. Hãy xem tài liệu tham khảo cho API này để biết thêm thông tin chi tiết về các thuộc tính này.
Thứ tự tham số
Có nhiều cách để các thư viện ứng dụng cấu trúc giao diện của chúng. Một cách là sử dụng một phương thức có từng tham số API trong chữ ký của phương thức. Tuy nhiên, vì JSON là một định dạng không có thứ tự, nên rất khó để biết theo phương thức lập trình cách sắp xếp các tham số trong chữ ký phương thức. Mảng parameterOrder cung cấp một thứ tự tham số cố định để đưa ra yêu cầu. Mảng này liệt kê tên của từng tham số theo thứ tự quan trọng; mảng này có thể chứa các tham số đường dẫn hoặc tham số truy vấn, nhưng mọi tham số trong mảng đều là tham số bắt buộc.
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 nghe nhìn đó 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.
Phương thức enable không chứa phần mediaUpload. Tuy nhiên, một phần mediaUpload điển hình có thể trông như sau:
"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 có hỗ trợ 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 nội dung nghe nhìn có thể tải lên.
Thuộc tính accept là danh sách media-ranges xác định những loại mime nào được phép tải lên. Điểm cuối xuất hiện 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 có đơn vị là 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 từng người dùng cho API đó, vì vậy, ngay cả khi nội dung tải lên nhỏ hơn maxSize, thư viện ứng dụng vẫn phải chuẩn bị để xử lý nội dung tải lên không thành công do không đủ dung lượng.
Mục protocols liệt kê các giao thức tải lên mà một phương thức hỗ trợ. Giao thức simple chỉ đơn giản là đăng nội dung nghe nhìn lên điểm cuối đã cho trong một yêu cầu HTTP duy nhất. 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 có thể tiếp tục. Nếu thuộc tính multipart là true thì điểm cuối sẽ chấp nhận tải lên nhiều phần, tức là cả yêu cầu JSON và nội dung nghe nhìn đều có thể được gói cùng nhau trong một nội dung mutlipart/related và gửi cùng nhau. Xin lưu ý rằng cả 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ư được nêu trong phần Soạn yêu cầu.
Tải nội dung nghe nhìn xuống
Nếu một phương thức hỗ trợ tải nội dung nghe nhìn xuống (chẳng hạn như hình ảnh, âm thanh hoặc video), thì điều đó sẽ được biểu thị bằng tham 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 chuỗi nối của servicePath và path là /youtube/v3/captions/{id}. Bạn nên tạo URL tải nội dung đa phương tiện xuống bằng /download ngay cả khi useMediaDownloadService là false.
Tham số chung
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 tham số cho từng phương thức, tuy nhiên, bạn có thể áp dụng các tham số này cho mọi phương thức trong API.
Ví dụ: các phương thức get và list của Service Usage API có thể có một 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 dễ đọc. Sau đây là danh sách các tham số phổ biến:
| Thông số | Ý nghĩa | Ghi chú | 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 tập hợp con gồm các trường cần đưa vào phản hồi. |
|
|
key |
Khoá API. (BẮT BUỘC) |
|
|
prettyPrint |
Trả về phản hồi có thụt lề và 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à bạn đang thực hiện lệnh gọi API. |
|
Tài liệu nội tuyến
Mỗi tài liệu Khám phá đều được chú thích bằng một số trường description cung cấp tài liệu nội tuyến cho API. Bạn có thể tìm thấy các trường description cho các phần tử API sau:
- Chính 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ố
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á API của Google để tạo tài liệu mà con người có thể đọc được cho một thư viện ứng dụng – ví dụ: JavaDoc.