API をタイプ プロバイダとして追加

このページでは、API をタイプ プロバイダとして Deployment Manager に追加する方法について説明します。タイプとタイプ プロバイダの詳細については、タイプの概要のドキュメントをお読みください。

タイプ プロバイダは、サードパーティの API のすべてのリソースを、設定で使用できる基本タイプとして Deployment Manager に公開します。これらのタイプは作成、読み取り、更新、削除(CRUD)をサポートする RESTful API によって直接提供される必要があります。

任意の API をタイプ プロバイダとして追加できますが、その API に OpenAPI 仕様(旧称 Swagger©)または Google Discovery ドキュメントがあることが条件となります。Google で自動的に提供されない API を使用するために、タイプ プロバイダを追加します。

このドキュメントでは、独自の API サービスを立ち上げる方法については説明しません。追加したい API がすでに存在しているか、公開エンドポイントからアクセスできる実行中の API をすでに作成済みであることが前提です。たとえば、Cloud Endpoints クイックスタートに従って Google Cloud Endpoints を使用して、サンプル API をデプロイできます。

始める前に

タイプ プロバイダのコンポーネント

タイプ プロバイダは次のコンポーネントで構成されます:

  • 名前: タイプ プロバイダの任意の名前。この名前を使用して、タイプと関連 API リソースを参照します。
  • 記述子ドキュメント: タイプの記述子ドキュメントの URL。サポートされるドキュメントには、Google Discovery ドキュメントまたは OpenAPI 1.2 仕様が含まれます。
  • 認証: API に対して必要とされる認証情報。基本認証を指定できます。API が Google Endpoints または Google Kubernetes Engine で実行される場合は、プロジェクトのサービス アカウント認証情報を認証として使用することもできます。
  • 詳細オプション: 入力マッピングの詳細オプションまたは API オプション。

名前

タイプ プロバイダの名前。この名前を使用して、将来の設定やテンプレートのタイプを示します。たとえば、タイプ プロバイダを作成して my-awesome-type-provider という名前を付けた場合、その後のテンプレートで次のように使用します:

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

ここで、my-project はタイプが属しているプロジェクト ID で、some-collection は作成する API リソースへのパスです。

記述子ドキュメント

タイプ プロバイダの記述子ドキュメントは OpenAPI 1.2 または 2.0 仕様、あるいは Google Discovery ドキュメントのいずれかで指定できます。たとえば、次の URL で、Compute Engine ベータ版の API の Google Discovery ドキュメントが見つかります。

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

Google Discovery ドキュメントの全リストをご覧ください。

また、OpenAPI 1.2OpenAPI 2.0 のドキュメントも受け入れられます。

認証

API で認証を必要とする場合、ここで認証の詳細を指定できます。Deployment Manager は、ユーザー名やパスワードなどの基本認証の認証情報をサポートしています。Google Kubernetes Engine と Google Cloud Endpoints では、Authorization ヘッダーを使用して、プロジェクトのサービス アカウントのアクセス トークンを提供できます。

基本認証を指定するには、credentials セクションにユーザー名とパスワードを入力します。

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

ユーザー名とパスワードを指定する必要があるのは、タイプ プロバイダを最初に作成したときだけです。

Google Kubernetes Engine で実行しているクラスタがある場合、Deployment Manager を使用して、そのクラスタをタイプ プロバイダとして追加し、Kubernetes API にアクセスすることができます。この場合、Deployment Manager を使用している同じプロジェクトでクラスタを実行していることを前提としています。このシナリオでは、プロジェクトの Google API サービス アカウントの OAuth 2.0 アクセス トークンを取得して、そのアクセス トークンを Authorization ヘッダーの中で指定できます。上記の認証情報セクションと異なり、リクエストでは入力マッピングとしてこれを指定する必要があります:

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

googleOauth2AccessToken() メソッドは、ユーザーがこのタイプ プロバイダを呼び出すと、自動的にアクセス トークンを取得します。完全な例については、GKE クラスタとタイプのサンプルをご覧ください。

同じ方法を使用して Google Cloud Endpoints に対して認証を行うことができます。

タイプの詳細オプション

一部の API には Deployment Manager で API のすべてのプロパティを Deployment Manager にマッピングすることを困難にする特性があります。理想的なシナリオでは、記述子ドキュメントを指定すると、ユーザー側では追加作業なしで、Deployment Manager が自動的に API リクエストのパスと関連する API プロパティを見つけ出します。複雑な API の場合、Deployment Manager はほとんどの API を理解できますが、明白ではない API の動作に対して明示的に入力マッピングを指定する必要がある場合があります。

入力マッピングの詳細については、API 詳細オプションのドキュメントをご覧ください。

タイプ プロバイダの作成

タイプ プロバイダを作成するには、目的のタイプ プロバイダ名、記述子の URL、必要な認証情報が含まれているリクエストのペイロードを使用して Deployment Manager に対してリクエストを行います。

gcloud

gcloud ツールを使用してタイプ プロバイダを作成するには、type-providers create コマンドを使用します。

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

ここで:

  • [TYPE_PROVIDER_NAME] は、このタイプに付ける名前です。
  • [URL] は、このタイプをサポートしている記述子ドキュメントの完全修飾 URL です。次に例を示します。

    http://petstore.swagger.io/v2/swagger.json
    

認証情報または API 詳細オプションを指定するには、YAML で記述された API オプション ファイルを作成して --api-options-file フラグで指定します。たとえば、ファイルは次のようになります。

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

gcloud コマンドは次のようになります。

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

API

API の基本タイプを作成するには、POST リクエストを作成し、descriptorUrl と省略可能な構成オプションをリクエスト本文の中で指定します。次に例を示します。

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

詳細については、insert メソッドのドキュメントをご覧ください。

タイプ プロバイダのテスト

タイプ プロバイダが期待どおりに動作していることを検証する手順は次のとおりです。

  1. 設定で新しいタイプ プロバイダを呼び出します
  2. タイプ プロバイダで提供されている各コレクションをデプロイし、API が期待どおりに動作していることを確認します。コレクションは、指定したタイプ プロバイダの API リソースです。
  3. 各コレクションを更新します
  4. 各コレクションを削除します

ユーザーがタイプ プロバイダのタイプをインスタンス化する場合、実際には基盤の API に対して明示的に行うのではなく、Deployment Manager に対してリクエストを行います。次に、Deployment Manager は提供された情報でリクエストを作成し、ユーザーに代わって API に対してリクエストを行います。最もよく見られる問題は、API に Deployment Manager が自動的に認識するのが困難なプロパティがあることです。たとえば、一部の API では、API のレスポンスからしか抽出できないプロパティが必要です。他にも、オペレーションに応じて異なる値を持つ同じフィールド名を使用する API があります。このような場合は、Deployment Manager に明示的にこれらのシナリオの処理方法を伝える必要があります。

API にこのような特性がある場合、入力マッピングを使用して、Deployment Manager に対して曖昧さを明確にします。

次のステップ

© 2016 Swagger. All rights reserved.

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Cloud Deployment Manager のドキュメント