このページは Cloud Translation API によって翻訳されました。

クライアントライブラリの構築

はじめに

Google API 検出サービスを使用して、Google API で使用するさまざまなツールを構築できます。ただし、ディスカバリドキュメントの主な目的は、Google がさまざまなプログラミング言語でクライアントライブラリを作成できるようにすることです。このセクションでは、Google API のカスタムクライアントライブラリを構築する方法について説明します。

安定した、完全なクライアントライブラリは複雑なツールで、開発に数か月かかることがあります。Google API のシンプルなクライアントライブラリを構築するための一般的な手順は、次の 3 つの簡単なステップに分けることができます。

ディスカバリドキュメントの取得と API サーフェスの作成
リクエストの作成
呼び出しとレスポンスの取得

これらの手順については、以降のセクションで詳しく説明します。また、例のセクションの Simple API クライアントのサンプルを見て、この手順がコードにどのようにマッピングされているかを確認できます。

ステップ 1: ディスカバリドキュメントを取得する

クライアントライブラリの実装を開始する前に、開発パスを進める方法に影響する基本的な要件がいくつかあります。たとえば、選択したプログラミング言語は、型付きか型なしのいずれかになります。型として指定する場合は、静的または動的に型付けできます。コンパイルまたは解釈される場合があります。これらの要件を満たすことで、ヒアリング調査ドキュメントを適切に使用、使用できます。

最初の開発タスクは、ディスカバリドキュメントを取得することです。いつドキュメントを取得するかは、特定した要件によって決まります。たとえば、静的に型付けされた言語の場合、プロセスの早い段階でディスカバリドキュメントを取得し、ディスカバリドキュメントで説明されている特定の API を処理するためのコードを生成できます。厳密に型指定された言語の場合、コードを生成してコンパイル済みライブラリをビルドすることもあります。型が動的に生成される言語の場合、プログラミングサーフェスを使用して、臨機応変に API と対話するためのプログラミング構造を必要に応じて構築できます。

ステップ 2: リクエストを作成する

リクエストを作成するには、次の 2 つの手順を行います。

リクエストの本文を作成する。
リクエスト URL の構成。

リクエストの本文がある場合は、それを適切な言語表現から適切な送信形式に変換する必要があります。たとえば Java クライアントライブラリでは、リクエストデータのタイプ操作を安全にし、JSON にシリアル化可能なリクエストタイプごとにクラスが存在することがあります。

リクエスト URL の構成は、やや複雑なプロセスになります。

API の各メソッドの path プロパティでは、URI テンプレート v04 構文を使用します。このプロパティには、中かっこで囲まれた変数が含まれている可能性があります。変数を含む path プロパティの例を次に示します。

/example/path/var

上記のパスにおいて、var は変数です。この変数の値は、そのメソッドのディスカバリドキュメントの parameters セクションから取得されます。各変数名に対応する値が parameters オブジェクトに格納されています。上記の例では、parameters セクションに var という名前のパラメータがあります（location プロパティが、パス変数であることを示すために path になっています）。

リクエストを行うときに、var の値を URL に置き換えます。たとえば、ライブラリのユーザーが var の値を foo に設定することを選択した場合、新しい URL は /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}

Google Cloud Service Management API を呼び出すには API キーが必要です。API キーを適用した後、API Discovery Service のサービス定義を取得するための完全な URI は次のようになります。

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

ステップ 3: 呼び出しを行ってレスポンスを処理する

リクエストを送信したら、レスポンスを適切な言語表現にシリアル化解除し、基盤となる HTTP トランスポートと API サービスから生成されるエラーメッセージの両方で、発生する可能性のあるエラー状態に対処する必要があります。エラーの形式については、Google JSON スタイルガイドをご覧ください。

Examples

Google API Discovery Service を使用して実装されたクライアントライブラリおよびツールの具体的な例については、ライブラリとサンプルのドキュメントをご覧ください。次のセクションでは、API クライアントライブラリの簡単な例を示します。

シンプルな API クライアント

以下は、Python3 で記述された非常に単純なクライアントライブラリの例です。クライアントは、Google Cloud Service Management API を操作するインターフェースを構築し、そのインターフェースを使用して API Discovery Service のサービス定義を取得します。

警告: 以下のコードは、一般的なクライアントライブラリの非常に簡略化されたバージョンです。クライアントライブラリ作成の側面を示すために不完全な方法で実装されています。これは本番環境に対応したコードではありません。

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 のパラメータは URL のクエリパラメータに挿入されます。最後に、ディスカバリドキュメントで指定された HTTP メソッドを使用して、作成された URL にリクエストを送信します。
ステップ 3.a: クライアントサーフェスを構築する
クライアントサーフェスは、解析されたディスカバリドキュメントに対して再帰的に降順で構築されます。methods セクションのメソッドごとに、Collection オブジェクトに新しいメソッドがアタッチされます。コレクションはネストできるため、resources を検索し、見つかったすべてのメンバーの Collection オブジェクトを再帰的に作成します。ネストされた各コレクションも、属性として Collection オブジェクトに付加されます。
ステップ 3.b: クライアントを使用する
これは、ビルドされた API サーフェスの使用方法を示します。まず、ディスカバリドキュメントからサービスオブジェクトが作成され、Google Cloud Service Management API を介して API Discovery Service のサービス定義が取得されます。

クライアント ライブラリの構築