建構用戶端程式庫

您可以使用 Google API 探索服務，建構各種不同的工具，搭配 Google API 使用。不過，探索文件的主要目的是讓 Google 以各種程式設計語言建立用戶端程式庫。本文件說明如何為 Google API 建構自訂用戶端程式庫。

穩定且功能完整的用戶端程式庫是項複雜的工具，可能需要數月才能開發完成。不過，針對 Google API 建構簡單用戶端程式庫的一般操作說明，可分為三個簡單步驟：

擷取探索文件並建構 API 途徑
撰寫要求
發出呼叫並擷取回應

下列各節將詳細說明這些步驟。您也可以參考「範例」一節中的「簡易 API 用戶端」範例，瞭解這些操作說明如何對應至程式碼。

擷取「探索」文件

開始實作用戶端程式庫前，請先瞭解一些基本要求，這些要求會影響您開發應用程式的進度。舉例來說，您選擇的程式設計語言可能會進行型別檢查或不進行型別檢查；如果進行型別檢查，則可能會進行靜態或動態型別檢查。可進行編譯或解譯。這些規定將引導您如何使用探索文件。

第一項開發工作是擷取 Discovery 文件。您要擷取文件的確切時機，取決於您所指定的要求。舉例來說，在靜態型別的語言中，您可能會在程序初期擷取 Discovery 文件，然後產生程式碼來處理 Discovery 文件所描述的特定 API。對於強型別的語言，您可以產生一些程式碼並建構編譯的程式庫。針對動態類型的語言，您可以延遲建構程式結構，以便在使用程式設計介面時，即時連結至 API。

撰寫要求

組合要求包含兩個步驟：

編寫要求主體。
建立要求網址。

您需要將要求主體 (如有) 從適合語言的表示法轉換為正確的電報格式。舉例來說，在 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，請按照下列步驟操作：

如果您知道自己的位置 (區域)，且 Discovery 文件含有 endpoints 屬性，請檢查您的位置是否出現在 endpoints 清單中。如果是，請從 endpoints 清單中取得 endpointUrl，其 location 與您的 location 相符。
如果 Discovery 文件中沒有 endpoints 資源，或是您的所在位置不在 endpoints 清單中，或是您想指定全球端點，請從 Discovery 文件的頂層取得 rootUrl 資源。

舉例來說， Service Usage API 的 Discovery 文件中的 rootUrl 屬性為：
```
https://serviceusage.s3nsapis.fr/
```
從探索文件的頂層擷取 servicePath。例如，Service Usage API 探索文件中的 servicePath 屬性為空白。
將這些字串連接起來，即可取得：
```
https://serviceusage.s3nsapis.fr/
```
取得 path 屬性，將其展開為 URI 範本，然後將該展開作業的結果與上一個步驟的 URI 結合。舉例來說，在 v1 服務用量 API 的 serviceusage.services.enable 方法中，path 屬性的值為 v1/{+name}:enable。因此，方法的完整 URI 如下：
```
https://serviceusage.s3nsapis.fr/v1/{+name}:enable
```

您不需要API 金鑰就能呼叫 Service Usage API。不過，如果您呼叫的 API 需要 API 金鑰，您可以將 API 金鑰新增至 URI 的查詢字串：

REQUEST_URI?key=API_KEY

撥打電話並處理回應

傳送要求後，您需要將回應反序列化為適當的語言表示法，並小心處理可能發生的錯誤狀態，包括基礎 HTTP 傳輸和 API 服務產生的錯誤訊息。錯誤格式已記錄在 Google JSON 樣式指南中。

範例

以下是 API 用戶端程式庫的簡單範例。

Simple APIs 用戶端

以下是用 Python 3 編寫的簡易用戶端程式庫範例。用戶端會建立用於與 Service Usage API 互動的介面，然後使用該介面在專案 my-project 中啟用 Compute Engine API (compute.googleapis.com)。

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.s3nsapis.fr/$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'))

用戶端的關鍵元件如下：

步驟 1：擷取「探索」文件。系統會擷取 Service Usage API 的探索文件，並將其剖析為資料結構。由於 Python 是動態類型的程式語言，因此可在執行階段擷取 Discovery 文件。
步驟 2.a：建構基礎 URI。系統會計算基礎 URI。
步驟 2.b：組合要求。在集合上呼叫方法時，URI 範本會擴充，並將傳入方法的參數，而位置為 query 的參數會放入網址的查詢參數。最後，系統會使用探索文件中指定的 HTTP 方法，將要求傳送至組合網址。
步驟 3.a：建構用戶端介面。您可以透過遞迴方式，在剖析的探索文件中遞迴下降，建構用戶端途徑。對於 methods 部分中的每個方法，系統會將新方法附加至 Collection 物件。由於集合可巢狀結構化，因此我們會尋找 resources，並針對所有成員遞迴建立 Collection 物件 (如果找到的話)。每個巢狀集合也會以屬性形式附加至 Collection 物件。
步驟 3.b：使用用戶端。這會示範如何使用已建構的 API 途徑。首先，我們會從探索文件建立服務物件，然後使用服務用量 API 在專案 my-project 中啟用 Compute Engine API。