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

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

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

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

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

始める前に

このガイドのコマンドラインの例を使用する場合、gcloud コマンドラインツールをインストールします。
このガイドの API の例を使用する場合は、API アクセスを設定します。
このガイドの API の例を使用する場合、v2beta API アクセスを設定します。

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

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

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

認証

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

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

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

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

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

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

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

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

（省略可）カスタム認証局のルート

API をタイププロバイダとして Deployment Manager に追加し、その API の HTTPS エンドポイントが公的に信頼できる認証局（CA）によって提供されていない証明書を使用して接続を暗号化する場合、以下の例のとおり API を構成に追加できます。

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

ここで my-gke-cluster は、使用している GKE クラスタです。詳細な例については、GKE プロバイダクラスタのサンプルをご覧ください。

タイプの詳細オプション

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

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

タイププロバイダの作成

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

gcloud

gcloud CLI でタイププロバイダを作成するには、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]

カスタム認証局（CA）を使用して認証を行う場合は、次の例のとおり CA を gcloud コマンドのフラグとして追加できます。

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

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 メソッドのドキュメントをご覧ください。

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

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

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

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

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

次のステップ

タイププロバイダを呼び出す方法について学びます。
他のプロジェクトとタイププロバイダを共有します。
タイプの詳細について学びます。
構成の作成について読みます。
デプロイを作成します。
API 詳細オプションの詳細について学びます。