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

Tạo thư viện ứng dụng

Bạn có thể sử dụng Dịch vụ Khám phá API của Google để tạo nhiều công cụ khác nhau nhằm sử dụng với các API của Google. Tuy nhiên, mục đích chính của tài liệu Khám phá là cho phép Google tạo các thư viện ứng dụng bằng nhiều ngôn ngữ lập trình. Tài liệu này mô tả cách bạn có thể xây dựng một thư viện ứng dụng tuỳ chỉnh cho các API của Google.

Một thư viện ứng dụng ổn định và đầy đủ tính năng là một công cụ phức tạp có thể mất nhiều tháng để phát triển. Tuy nhiên, hướng dẫn chung về cách tạo một thư viện ứng dụng đơn giản cho API của Google có thể được chia thành 3 bước đơn giản:

Tìm nạp tài liệu Khám phá và tạo giao diện API
Soạn yêu cầu
Thực hiện cuộc gọi và tìm nạp phản hồi

Các bước này được mô tả chi tiết hơn trong các phần sau. Bạn cũng có thể xem mẫu Ứng dụng API đơn giản trong phần Ví dụ để biết cách các hướng dẫn này tương ứng với mã.

Tìm nạp tài liệu Khám phá

Trước khi bắt đầu triển khai một thư viện ứng dụng, bạn cần đáp ứng một số yêu cầu cơ bản ảnh hưởng đến cách bạn sẽ tiếp tục trên con đường phát triển. Ví dụ: ngôn ngữ lập trình mà bạn chọn có thể là ngôn ngữ có kiểu hoặc không có kiểu; nếu là ngôn ngữ có kiểu thì có thể là ngôn ngữ có kiểu tĩnh hoặc có kiểu động. Có thể được biên dịch hoặc diễn giải. Những yêu cầu này sẽ hướng dẫn bạn cách sử dụng và dùng tài liệu Khám phá.

Tác vụ phát triển đầu tiên là tìm nạp tài liệu Khám phá. Chiến lược của bạn về thời điểm chính xác cần tìm nạp tài liệu được xác định theo các yêu cầu mà bạn đã xác định. Ví dụ: trong một ngôn ngữ được nhập tĩnh, bạn có thể tìm nạp tài liệu Khám phá sớm trong quy trình, sau đó tạo mã để xử lý API cụ thể được mô tả trong tài liệu Khám phá. Đối với một ngôn ngữ có kiểu dữ liệu mạnh, bạn có thể tạo một số mã và tạo một thư viện đã biên dịch. Đối với một ngôn ngữ được nhập động, bạn có thể tạo một cách chậm rãi các cấu trúc lập trình để giao tiếp với API ngay lập tức khi sử dụng giao diện lập trình.

Soạn yêu cầu

Việc tạo yêu cầu bao gồm 2 bước riêng biệt:

Soạn nội dung yêu cầu.
Tạo URL yêu cầu.

Bạn cần chuyển đổi nội dung yêu cầu (nếu có) từ một biểu diễn phù hợp với ngôn ngữ sang định dạng truyền dữ liệu chính xác. Ví dụ: trong thư viện ứng dụng Java, có thể có một lớp cho từng loại yêu cầu cho phép thao tác an toàn về kiểu đối với dữ liệu yêu cầu và có thể chuyển đổi tuần tự thành JSON.

Việc tạo URL yêu cầu là một quy trình phức tạp hơn một chút.

Thuộc tính path của mỗi phương thức trong API sử dụng cú pháp URI Template v04. Thuộc tính này có thể chứa các biến được đặt trong dấu ngoặc nhọn. Sau đây là ví dụ về một thuộc tính path có các biến:

/example/path/var

Trong đường dẫn ở trên, var là một biến. Giá trị của biến này xuất phát từ phần parameters của tài liệu Khám phá cho phương thức đó. Mỗi tên biến đều có một giá trị tương ứng trong đối tượng parameters. Trong ví dụ trên, có một tham số tên là var trong phần parameters (và thuộc tính location của tham số này là path để cho biết đây là một biến đường dẫn).

Khi đưa ra yêu cầu, bạn nên thay thế giá trị cho var vào URL. Ví dụ: nếu người dùng thư viện chọn đặt var thành giá trị foo, thì URL mới sẽ là /example/path/foo.

Ngoài ra, xin lưu ý rằng thuộc tính path là một URI tương đối. Để tính URI tuyệt đối, hãy làm theo các bước sau:

Nếu bạn biết vị trí (khu vực) của mình và tài liệu Khám phá có thuộc tính endpoints, hãy kiểm tra xem vị trí của bạn có trong danh sách endpoints hay không. Nếu có, hãy lấy endpointUrl từ danh sách endpoints có location khớp với location của bạn.
Nếu không có tài sản endpoints trong tài liệu Khám phá hoặc vị trí của bạn không có trong danh sách endpoints hoặc bạn muốn nhắm đến điểm cuối toàn cầu, hãy lấy tài sản rootUrl từ cấp cao nhất của tài liệu Khám phá.

Ví dụ: thuộc tính rootUrl trong Tài liệu khám phá cho Service Usage API là:
```
https://serviceusage.googleapis.com/
```
Lấy servicePath từ cấp cao nhất của tài liệu Khám phá. Ví dụ: thuộc tính servicePath trong tài liệu Khám phá cho Service Usage API (API Mức sử dụng dịch vụ) là trống.
Nối chúng lại với nhau để có được:
```
https://serviceusage.googleapis.com/
```
Lấy thuộc tính path, mở rộng thuộc tính này dưới dạng Mẫu URI và kết hợp kết quả của việc mở rộng đó với URI ở bước trước. Ví dụ: trong phương thức serviceusage.services.enable của Service Usage API phiên bản 1, giá trị của thuộc tính path là v1/{+name}:enable. Vì vậy, URI đầy đủ cho phương thức này là:
```
https://serviceusage.googleapis.com/v1/{+name}:enable
```

Bạn không cần khoá API để gọi Service Usage API. Tuy nhiên, nếu API mà bạn đang gọi yêu cầu khoá API, thì bạn có thể thêm khoá API vào chuỗi truy vấn của URI:

REQUEST_URI?key=API_KEY

Gọi điện và xử lý phản hồi

Sau khi gửi yêu cầu, bạn cần giải tuần tự hoá phản hồi thành biểu thị ngôn ngữ thích hợp, chú ý xử lý các điều kiện lỗi có thể xảy ra – cả trong quá trình truyền HTTP cơ bản và thông báo lỗi do dịch vụ API tạo. Định dạng của các lỗi được ghi lại trong Hướng dẫn về kiểu JSON của Google.

Ví dụ

Phần sau đây đưa ra một ví dụ đơn giản về thư viện ứng dụng API.

Ứng dụng Simple APIs

Dưới đây là ví dụ về một thư viện ứng dụng rất đơn giản được viết bằng Python3. Ứng dụng tạo một giao diện để tương tác với Service Usage API, sau đó dùng giao diện đó để bật Compute Engine API (compute.googleapis.com) trong dự án my-project.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).items():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.parse.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).items():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).items():
    setattr(collection, name, createNewMethod(name, method))
  return collection

# Step 3.b: Use the client
service = build(discovery, Collection())
print (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

Các thành phần quan trọng của ứng dụng khách là:

Bước 1: Tìm nạp tài liệu Khám phá. Tài liệu Khám phá cho Service Usage API được truy xuất và phân tích cú pháp thành một cấu trúc dữ liệu. Vì Python là một ngôn ngữ được nhập động, nên bạn có thể tìm nạp tài liệu Khám phá trong thời gian chạy.
Bước 2.a: Tạo URI cơ sở. URI cơ sở được tính toán.
Bước 2.b: Soạn yêu cầu. Khi một phương thức được gọi trên một tập hợp, URI Template sẽ được mở rộng bằng các tham số được truyền vào phương thức và các tham số có vị trí query sẽ được đưa vào các tham số truy vấn của URL. Cuối cùng, một yêu cầu sẽ được gửi đến URL đã tạo bằng phương thức HTTP được chỉ định trong tài liệu Khám phá.
Bước 3.a: Tạo giao diện người dùng. Giao diện ứng dụng được tạo bằng cách giảm dần đệ quy trên tài liệu Discovery đã phân tích cú pháp. Đối với mỗi phương thức trong phần methods, một phương thức mới sẽ được đính kèm vào đối tượng Collection. Vì các bộ sưu tập có thể được lồng vào nhau, nên chúng ta sẽ tìm resources và tạo đệ quy một đối tượng Collection cho tất cả các thành phần của đối tượng đó nếu tìm thấy. Mỗi tập hợp lồng nhau cũng được đính kèm dưới dạng một thuộc tính vào đối tượng Collection.
Bước 3.b: Sử dụng ứng dụng. Điều này minh hoạ cách sử dụng giao diện API đã tạo. Trước tiên, một đối tượng dịch vụ được tạo từ tài liệu Discovery, sau đó API Mức sử dụng dịch vụ được dùng để bật Compute Engine API trong dự án my-project.