API を統合するための API の要件

このドキュメントでは、Deployment Manager へのタイプ プロバイダとして追加する API の一般的な要件について説明します。以下のガイドラインで、Deployment Manager が想定する API の特性を理解します。API がここに記述する仕様と正確に一致しない場合、拡張 API オプションを使用すると、この不整合を解決できることがあります。

API に有効な記述子ドキュメントが含まれる

記述子ドキュメントには API とそのリソースが記載されています。Deployment Manager には、OpenAPI 仕様または Google Discovery 記述子ドキュメントに基づく API だけを統合できます。OpenAPI 仕様の作成方法に関する総合的な情報については、OpenAPI GitHub リポジトリをご覧ください。

API の記述子ドキュメント エンドポイントにアクセスできる

Deployment Manager が API の記述子ドキュメントを取得する HTTP リクエストを作成するため、Deployment Manager がアクセスできる場所に記述子ドキュメントをホストする必要があります。場所は一般公開されている URL か、基本認証によって保護されるエンドポイントになります。

API が特定の Google サービスでホストされている場合、基本認証または OAuth2 を受け入れる

Deployment Manager は、Google Kubernetes Engine または Google Endpoints でホストされている特定の API に対して、現在、基本認証（ユーザー名とパスワード）と OAuth 2.0 認証をサポートしています。プロジェクトのサービス アカウントを使用して、認証をセットアップできます。

詳細については、タイプ プロバイダの作成をご覧ください。

作成、読み取り、更新、削除（CRUD）オペレーションをサポート

対象となる API は、CRUD オペレーションをサポートする RESTful API である必要があります。つまり、以下を実行するメソッドが存在します。

  • 作成オペレーション - リソースを作成します。これは HTTP POST リクエストである必要があります。
  • 読み取りオペレーション - API リソースに関する情報を取得します。これは HTTP GET リクエストである必要があります。
  • 更新オペレーション - リソースを更新します。これは HTTP PUT リクエストである必要があります。
  • 削除オペレーション - リソースを削除します。これは HTTP DELETE リクエストである必要があります。

一部の CRUD オペレーションのみをサポートする API も機能しますが、動作は利用できるオペレーションによって異なります。

GET リクエストのサポート CREATE リクエストのサポート UPDATE リクエストのサポート DELETE リクエストのサポート 特殊な API 動作
○ ○ ○ ○ なし。
○ ○ ○ × ユーザーはリソースを放棄することはできますが、削除はできません。
○ ○ × ○ 既存のリソースの変更がすべて失敗します。リソースを更新するには、削除してから再作成する必要があります。
○ ○ × × 上述の両方の動作。
○ × ○ ○ API が作成リクエストをサポートしない場合、ユーザーは ACQUIRE ポリシーでデプロイメントを更新して、そのデプロイメントに既存のリソースを追加することができます。
○ × ○ × ユーザーはリソースを取得するか、取得後更新できますが、削除はできません。
○ × × ○ ユーザーはリソースを削除するか、取得することができます。または、既存のリソースをデプロイメントに追加することができます。
○ × × × ユーザーは既存のリソースを取得するか、ABANDON ポリシーでリソースを削除することができます。

すべてのパスパラメータとクエリ パラメータを正常に解決

API のすべてのパスパラメータとクエリ パラメータはリソースの本文の一部として存在するか、API のすべてのメソッドに存在する必要があります。これで Deployment Manager は、ユーザーがパラメータを指定するときにパラメータを一致させることができます。以下の条件はパスパラメータとクエリ パラメータに適用されます。

POST 用のすべてのパス/クエリ パラメータは PUT 用のパラメータである必要がある

以下は、myParameter が PUT 用ではなく POST 用に存在しているため、無効です。

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

POST 以外のメソッドに対するすべてのパラメータは、このパラメータがサーバーで生成されたことを条件として、すべてのメソッド インターフェース内か、リソースの一部として存在している必要がある

最良のシナリオでは API が次のようになり、name パラメータはすべてのメソッドに表示されます。

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

別のシナリオとしては、メソッドのパスパラメータとして表示されるフィールドが、他のメソッドのパスパラメータとしては表示されることはありません。この場合、フィールドは API リソースの一部である必要があります。例:

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

この例で、id は POST リクエストを作成するときには存在しないが、リソースには存在するサーバーによって生成された値であることが前提となっています。id プロパティが既存のリソースにリクエストを作成するために必要であるにもかかわらず、このプロパティがリソースに存在しないか、パスで利用できない場合、API を Deployment Manager に移植することが難しくなります。

一部の API 動作には追加の構成が必要

一部の API 動作では、API を Deployment Manager に統合するため、追加の API 設定が必要となります。このような動作には次のものがあります。

  • サーバーで生成された値: 一部の API リソースには、各リクエストの後、または特定のイベントが API で発生したときに変わる、サーバーによって生成されたプロパティがあります。リクエストが作成されるたびにこの新しい値を取得するように、Deployment Manager に通知する拡張 API オプションを使用できます。

    たとえば、API は、更新リクエストを許可する前に、リソースの最新のフィンガープリント プロパティが必要になることがあります。拡張 API オプションを使用して、ユーザーがこの値によってデプロイメントを更新するリクエストを作成するたびに、Deployment Manager にこの値を取得するように通知します。

  • ユーザー入力の操作: たとえば、API でフィールドの値の先頭に常にプロジェクト ID が付いている必要がある場合、入力マッピングを使用すると、ユーザーにその情報を手動で追加させる代わりに、自動的に追加できます。

  • メソッドごとに変わるフィールド値: 異なる値をもつ同じフィールドを再利用するメソッドでは、API オプションを使用して、どの値をいつ使用するかを Deployment Manager に示すことができます。

詳細については、拡張 API オプションの設定をご覧ください。

次のステップ