Some or all of the information on this page might not apply to Cloud de Confiance by S3NS. See Differences from Google Cloud for more details.

建構用戶端程式庫

您可以使用 Google API Discovery Service，建構各種工具，與 Google API 搭配使用。不過，導覽文件的主要用途是讓 Google 以各種程式設計語言建立用戶端程式庫。這份文件說明如何為 Google API 建構自訂用戶端程式庫。

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

擷取導覽文件並建構 API 介面
撰寫要求
發出呼叫並擷取回應

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

擷取導覽文件

開始實作用戶端程式庫前，請先瞭解一些基本需求，這些需求會影響您後續的開發流程。舉例來說，您選擇的程式設計語言可能屬於有型別或無型別。如果是有型別，則可能屬於靜態或動態型別。這類語言可能會經過編譯或解譯。這些規定將引導您以適當的方式使用導覽文件。

第一項開發工作是擷取導覽文件。您所確定的需求會決定何時該擷取文件。舉例來說，在靜態型別語言中，您可能會在程序初期擷取導覽文件，然後產生程式碼來處理導覽文件所述的特定 API；如果是強型別語言，您可能要產生一些程式碼，並建構已編譯的程式庫；如果是動態型別語言，您可以在使用程式設計介面時，即時建構程式設計結構，與 API 介接。

撰寫要求

撰寫要求包含兩個步驟：

撰寫要求主體。
建構要求網址。

如有要求主體，您必須將其從適當的語言表示法轉換為正確的線路格式。舉例來說，在 Java 用戶端程式庫中，每個要求類型可能都有一個類別，可讓您以類型安全的方式操控要求資料，並序列化為 JSON。

建構要求網址的程序稍微複雜一些。

API 中每個方法的 path 屬性都會使用 URI 範本 v04 語法。這項屬性可能包含以大括號括住的變數。以下是含有變數的 path 屬性範例：

/example/path/var

在上述路徑中，var 是變數。這個變數的值來自該方法的導覽文件 parameters 部分。每個變數名稱在 parameters 物件中都有對應的值。在上述範例中，var 是 parameters 部分中的參數 (且其 location 屬性為 path，表示這是路徑變數)。

提出要求時，請將 var 的值代入網址。舉例來說，如果程式庫使用者選擇將 var 設為 foo 值，則新網址會是 /example/path/foo。

另請注意，path 屬性是相對 URI。如要計算絕對 URI，請按照下列步驟操作：

如果您知道自己的位置 (區域)，且導覽文件具有 endpoints 屬性，請檢查 endpoints 清單是否列出您的位置。如果有，請從 endpoints 清單中擷取 endpointUrl，其 location 與您的相符。
如果導覽文件中沒有 endpoints 屬性，或 endpoints 清單未列出您的位置，或者您想指定全域端點，請從導覽文件的頂層擷取 rootUrl 屬性。

舉例來說，Service Usage API 的導覽文件中的 rootUrl 屬性如下：
```
https://serviceusage.s3nsapis.fr/
```
從導覽文件的頂層擷取 servicePath。舉例來說，Service Usage API 的導覽文件中的 servicePath 屬性為空白。
將這些值串連在一起，即可取得：
```
https://serviceusage.s3nsapis.fr/
```
擷取 path 屬性，將其展開為 URI 範本，然後將展開結果與上一個步驟中的 URI 合併。舉例來說，在 v1 Service Usage 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 用戶端程式庫範例。

簡易 API 用戶端

以下範例是以 Python3 編寫的簡易用戶端程式庫。用戶端會建構介面，與 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 是動態型別語言，因此可以在執行階段擷取導覽文件。
步驟 2.a：建構基本 URI。系統會計算基礎 URI。
步驟 2.b：撰寫要求。對集合呼叫方法時，系統會使用傳遞至該方法的參數擴充 URI 範本，並將位置為 query 的參數加入網址的查詢參數中。最後，系統會使用導覽文件中指定的 HTTP 方法，將要求傳送至組成的網址。
步驟 3.a：建構用戶端介面。用戶端介面是透過遞迴下降剖析的導覽文件所建構。methods 部分中的每個方法都會附加至 Collection 物件。由於集合可以巢狀結構，因此我們會尋找 resources，並為所有成員遞迴建構 Collection 物件 (如有找到)。每個巢狀集合也會以屬性形式附加至 Collection 物件。
步驟 3.b：使用用戶端。這個範例會示範如何使用建構的 API 介面。首先，系統會從導覽文件建構服務物件，然後使用 Service Usage API 在專案 my-project 中啟用 Compute Engine API。