引言
你可以使用 Google API 探索服務來建立各種不同的工具，以便搭配 Google API 使用。不過，探索文件的主要用途是允許 Google 建立各種程式設計語言的用戶端程式庫。本節將說明如何為 Google API 建立自訂用戶端程式庫。
穩定且功能完備的用戶端程式庫是一項複雜的工具，可能需要數月才能完成開發。不過，為 Google API 建立簡易用戶端程式庫的一般操作說明可分為三個簡單的步驟：
- 擷取探索文件並建構 API 介面
- 撰寫要求
- 撥打電話並擷取回應
以下各節將詳細介紹這些步驟。您也可以查看「範例」部分中的「簡易 API 用戶端」範例，查看這些指示如何對應至程式碼。
步驟 1：擷取探索文件
在開始導入用戶端程式庫前，有些基本規定會影響您繼續開發路徑。舉例來說，您選擇的程式設計語言可能是已輸入或未輸入；如果是輸入，可能是靜態或動態輸入的。這可能經過編譯或解讀。這些規定將引導您使用和探索探索文件。
第一項開發工作是擷取探索文件。實際擷取文件的策略取決於您指定的規定。舉例來說，如果是靜態類型的語言，您可以在程序早期擷取「探索」文件，然後產生程式碼來處理「探索」文件描述的特定 API。如果是強類型輸入的語言，您可以產生一些程式碼並建構經過編譯的程式庫。針對動態類型的語言，您可以延遲建構程式設計結構，以便在使用程式設計介面時即時連線至 API。
步驟 2：提出要求
合併要求包含兩個不同的步驟：
- 編寫要求主體。
- 建構要求網址。
您需要將要求主體從適用語言的表示法轉換成正確的傳輸格式。舉例來說，在 Java 用戶端程式庫中，每個要求類型都有一個類別，允許對要求資料的類型安全操控，並且可序列化為 JSON。
要求網址的建構程序略為複雜。
API 中每個方法的 path 屬性都使用 URI 範本 v04 語法。這個屬性可能包含變數，並以大括號括住。以下是含有變數的 path 屬性範例：
/example/path/var
在上述路徑中，var 是變數。這個變數的值來自該方法的探索文件 parameters 區段。每個變數名稱在 parameters 物件中都有對應的值。在上述範例中，parameters 區段中有一個名為 var 的參數 (其 location 屬性為 path，表示這是路徑變數)。
提出要求時，請將 var 的值替換為網址。舉例來說，如果程式庫使用者選擇將 var 設為 foo 值，則新網址會是 /example/path/foo。
另請注意，path 屬性是相對 URI。如要計算絕對 URI，請按照下列步驟操作：
從探索文件頂層擷取
rootUrl屬性。
舉例來說，Google Cloud Service Management API 的探索文件中的rootUrl屬性為：https://servicemanagement.googleapis.com/從探索文件頂層擷取
servicePath。
舉例來說，Google Cloud Service Management API 的探索說明文件中的servicePath屬性為空白。將兩者串連在一起，就能獲得：
https://servicemanagement.googleapis.com/擷取
path屬性並展開為 URI 範本，然後將該展開的結果與上一個步驟的 URI 合併。
舉例來說，在 Google Cloud Service Management API 的get服務方法中，path屬性的值為v1/services/{serviceName}。因此，方法的完整 URI 如下：https://servicemanagement.googleapis.com/v1/services/{serviceName}
您必須具備 API 金鑰，才能呼叫 Google Cloud Service Management API。因此，套用 API 金鑰後，取得 API 探索服務服務定義的完整 URI 如下：
https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY
步驟 3：撥打電話及處理回應
傳送要求後，您必須將回應反序列化為適當的語言表示法，務必處理基礎 HTTP 傳輸和 API 服務產生的錯誤訊息。錯誤錯誤已記錄在 Google JSON 樣式指南中。
範例
如需使用 Google API 探索服務實作的用戶端程式庫和工具的具體範例，請參閱程式庫和範例文件。此外，本節將提供 API 用戶端程式庫的簡單範例。
簡單的 API 用戶端
以下是以 Python3 編寫的簡易用戶端程式庫範例。用戶端會建立與 Google Cloud Service Management API 互動的介面，然後使用該介面取得 API 探索服務的服務定義。
警告：下列程式碼是一般用戶端程式庫的簡易版本。此程式碼不完整，旨在示範建構用戶端程式庫的某些方面。它不是可用於實際工作環境的程式碼。
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'))
用戶端的主要元件如下：
- 步驟 1：擷取探索文件
Google Cloud Service Management API 的探索文件會擷取並剖析為資料結構。由於 Python 是動態的輸入語言，因此可在執行階段擷取探索文件。 - 步驟 2.a：建構基準 URI。
基本 URI 會計算完成。 - 步驟 2.b：撰寫要求。
在集合中呼叫方法時，URI 範本會擴展至方法中的參數，而含有query位置的參數會放入網址的查詢參數。最後，要求使用探索文件中指定的 HTTP 方法，傳送至組合網址。 - 步驟 3.a：建構用戶端介面。
用戶端表面的建構方式是以遞迴遞減的方式剖析剖析的探索文件。對於methods區段中的每個方法，新方法會附加至Collection物件。由於集合可以使用巢狀結構，我們會搜尋resources，然後找到所有成員的Collection物件 (如有找到)，每個巢狀集合也會以屬性形式附加至Collection物件。 - 步驟 3.b：使用用戶端。
這示範瞭如何使用建構的 API 介面。首先，透過探索文件建構服務物件，然後透過 Google Cloud Service Management API 擷取 API 探索服務的服務定義。