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

Xây dựng thư viện ứng dụng

Giới thiệu

Bạn có thể sử dụng Dịch vụ khám phá của các API của Google để xây dựng nhiều công cụ để 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á này 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. Phần 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.

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 vài tháng để phát triển. Tuy nhiên, bạn có thể chia nhỏ các hướng dẫn chung về cách tạo thư viện ứng dụng đơn giản cho các API của Google thành ba bước đơn giản:

Tìm nạp tài liệu Khám phá và xây dựng nền tảng API
Soạn thảo yêu cầu
Gọi điện 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 Simple client API trong phần Ví dụ để xem cách các hướng dẫn này ánh xạ tới mã.

Bước 1: Tìm nạp tài liệu Khám phá

Trước khi bắt đầu triển khai thư viện ứng dụng, có một số yêu cầu cơ bản sẽ ảnh hưởng đến cách bạn tiếp tục lộ trình phát triển. Ví dụ: ngôn ngữ lập trình bạn chọn có thể được nhập hoặc không nhập; nếu được nhập, nó có thể được nhập tĩnh hoặc động. Nội dung mô tả 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 tiếp cận việc sử dụng và sử dụng tài liệu Khám phá.

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

Bước 2: Soạn yêu cầu

Việc soạn một yêu cầu bao gồm hai bước riêng biệt:

Soạn thảo 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ừ phần trình bày phù hợp theo ngôn ngữ sang đúng định dạng lưới. Ví dụ: trong thư viện ứng dụng Java, có thể có một lớp cho mỗi loại yêu cầu cho phép thao tác an toàn với loại dữ liệu yêu cầu và được 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 mẫu v04. Thuộc tính này có thể chứa các biến được đặt trong dấu ngoặc nhọn. Dưới đây là ví dụ về 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 được lấy từ mục parameters của tài liệu Khám phá cho phương thức đó. Mỗi tên biến có một giá trị tương ứng trong đối tượng parameters. Trong ví dụ trên, có một tham số có tên 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 thực hiện yêu cầu, bạn nên thay thế giá trị của var vào URL. Ví dụ: nếu người dùng thư viện đưa ra lựa 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:

Lấy thuộc tính 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 API Quản lý dịch vụ đám mây của Google là:

https://servicemanagement.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 API Quản lý dịch vụ đám mây của Google trống.
Hãy nối chúng lại với nhau để:

https://servicemanagement.googleapis.com/
Kéo thuộc tính path vào, mở rộng thuộc tính này làm mẫu URI và kết hợp kết quả mở rộng đó với URI từ bước trước.
Ví dụ: trong phương thức dịch vụ get của API Google Cloud Service Management, giá trị của thuộc tính path là v1/services/{serviceName}. Vì vậy, URI đầy đủ cho phương thức này là:

https://servicemanagement.googleapis.com/v1/services/{serviceName}

Cần có khóa API để gọi API Quản lý dịch vụ đám mây của Google. Vì vậy, sau khi áp dụng khoá API, URI đầy đủ để lấy định nghĩa dịch vụ của API Discovery Service là:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

Bước 3: 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ự phản hồi thành nội dung trình bày bằng ngôn ngữ thích hợp, cẩn thận xử lý các điều kiện lỗi có thể xảy ra — cả trong thông tin truyền tải HTTP cơ bản và thông báo lỗi được tạo từ dịch vụ API. Định dạng của lỗi được ghi lại trong Hướng dẫn định kiểu JSON của Google.

Ví dụ

Để biết một số ví dụ cụ thể về thư viện ứng dụng và công cụ đã được triển khai bằng Dịch vụ khám phá API của Google, hãy xem tài liệu Thư viện và mẫu. Ngoài ra, phần sau đây cung cấp ví dụ đơn giản về thư viện ứng dụng API.

Ứng dụng API đơn giản

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 . Máy khách tạo một giao diện để tương tác với API Quản lý dịch vụ đám mây của Google, sau đó lấy định nghĩa dịch vụ về Dịch vụ khám phá API bằng giao diện đó.

Cảnh báo: mã bên dưới là phiên bản đơn giản hoá đáng kể của thư viện ứng dụng khách thông thường. Đây là một cách triển khai chưa hoàn chỉnh được cung cấp để minh hoạ một số khía cạnh của việc xây dựng thư viện ứng dụng. Đây chưa phải là mã có thể sản xuất.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + 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 (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

Các thành phần chính của ứng dụng bao gồm:

Bước 1: Tìm nạp tài liệu Khám phá.
Tài liệu Khám phá cho API Quản lý dịch vụ đám mây của Google đượ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ữ 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: Xây dựng 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, mẫu URI sẽ được mở rộng cùng với các tham số được truyền vào phương thức này và các tham số có vị trí là query được đưa vào tham số truy vấn của URL. Cuối cùng, một yêu cầu được gửi đến URL đã soạn bằng cách sử dụng phương thức HTTP được chỉ định trong tài liệu Khám phá.
Bước 3.a: Xây dựng nền tảng máy khách.
Giao diện khách hàng được xây dựng bằng cách giảm dần định kỳ trên tài liệu Khám phá được 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 tập hợp có thể được lồng vào nhau nên chúng ta tìm resources và định kỳ tạo một đối tượng Collection cho tất cả thành viên nếu phát hiện thấy một đối tượng. 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 cho đối tượng Collection.
Bước 3.b: Sử dụng ứng dụng.
Biểu đồ này minh hoạ cách sử dụng nền tảng API đã tạo. Trước tiên, đối tượng dịch vụ được tạo từ tài liệu Khám phá, sau đó định nghĩa dịch vụ của Dịch vụ khám phá API được truy xuất thông qua API quản lý dịch vụ đám mây của Google.