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

ESP を使用した App Engine フレキシブル環境（.NET）での Cloud Endpoints のスタートガイド

このチュートリアルでは、App Engine フレキシブル環境のインスタンスで実行されるサンプル .NET Core API および Extensible Service Proxy（ESP）を構成し、デプロイする方法について説明します。サンプル API は、OpenAPI 仕様を使用して作成されています。このチュートリアルでは、API キーを作成して API に対するリクエストで使用する方法も説明します。

Cloud Endpoints の概要については、Endpoints についてと Endpoints アーキテクチャをご覧ください。

目標

タスクの概要を示す次のリストを参照しながら、チュートリアルを実施してください。API にリクエストを送信するには、すべてのタスクを行う必要があります。

Google Cloud プロジェクトをセットアップして、必要なソフトウェアをインストールし、App Engine アプリケーションを作成します。始める前にをご覧ください。
サンプルコードをダウンロードします。サンプルコードを取得するをご覧ください。
Endpoints の構成に使用する openapi.yaml ファイルを構成します。Endpoints を構成するをご覧ください。
Endpoints 構成をデプロイして、Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
サンプル API と ESP を App Engine にデプロイします。API バックエンドをデプロイするをご覧ください。
API にリクエストを送信します。API にリクエストを送信するをご覧ください。
API の活動を追跡します。API の活動を追跡するをご覧ください。
Google Cloud アカウントに課金されないようにします。クリーンアップをご覧ください。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

後で必要になるため、プロジェクト ID をメモしておきます。
このチュートリアルでは .NET Core 2.x SDK が必要です。この SDK は任意のテキストエディタで使用できます。統合開発環境（IDE）は必須ではありませんが、利便性を考慮し、以下のいずれかの IDE の使用をおすすめします。
- Visual Studio Code。macOS、Linux、Windows で動作します。Visual Studio Code を使用する場合は、必ず .NET Core 2.x もインストールしてください。
- Visual Studio 2017 for Windows。.NET Core 2.x が含まれています。Visual Studio 2017 を使用している場合は、Google Tools for Visual Studio プラグインを使用することをおすすめします。このプラグインは App Engine のデプロイを IDE 内で統合します。
- Visual Studio for Mac。.NET Core 2.x が含まれています。
サンプル API にリクエストを送信するためのアプリケーションが必要です。このチュートリアルでは、PowerShell 3.0 以降でサポートされる Invoke-WebRequest を使った例を示します。
Google Cloud CLI をダウンロードします。
gcloud CLI を更新し、Endpoints コンポーネントをインストールします。
```
gcloud components update
```
Google Cloud CLI（gcloud）が、 Google Cloudにある対象のデータとサービスへのアクセスが許可されていることを確認します。
```
gcloud auth login
```
表示された新しいブラウザタブで、アカウントを選択します。
デフォルトプロジェクトを実際のプロジェクト ID に設定します。
```
gcloud config set project YOUR_PROJECT_ID
```
YOUR_PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。他にも Google Cloud プロジェクトがあり、gcloud を使用してそれらのプロジェクトを管理する場合は、gcloud CLI 構成の管理をご覧ください。
App Engine アプリケーションを作成するリージョンを選択します。次のコマンドを実行してリージョンのリストを取得します。
```
gcloud app regions list
```
App Engine アプリケーションを作成します。YOUR_PROJECT_ID は実際の Google Cloudプロジェクト ID に、YOUR_REGION は App Engine アプリケーションを作成するリージョンに置き換えます。
```
  gcloud app create \
  --project=YOUR_PROJECT_ID \
  --region=YOUR_REGION
```

サンプルコードの取得

サンプルの API をダウンロードするには:

.zip 形式のサンプルコードをダウンロードします。
.zip ファイルを解凍し、dotnet-docs-samples-master\endpoints\getting-started ディレクトリに移動します。
GettingStarted.sln を Visual Studio で開きます。あるいは、いつも使っているエディタで endpoints\getting-started\src\IO.Swagger ディレクトリにあるファイルを編集します。

Endpoints を構成する

OpenAPI 2.0 または OpenAPI 3.x に基づいて、アプリの surface と認証要件を記述する OpenAPI ドキュメントを用意する必要があります。詳細については、サポートされている OpenAPI バージョンをご覧ください。

また、ESPv2 がアプリを呼び出すために必要な情報を取得できるよう、このドキュメントには各アプリの URL を設定した Google 固有のフィールドも追加する必要があります。OpenAPI を初めて使用する場合は、OpenAPI の概要で詳細をご覧ください。

OpenAPI 2.0

OpenAPI 2.0 仕様を使用して Endpoints を構成するには、ダウンロードしたサンプルコードの dotnet-docs-samples-master\endpoints\getting-started ディレクトリにある openapi-appengine.yaml ファイルを使用します。

OpenAPI 2.0 仕様の内容は次のようになります。

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR_PROJECT_ID.appspot.com"
consumes:
- "application/json"
produces:
- "application/json"
schemes:
- "https"
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authentication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_jwt:
          audiences:
          # This must match the "aud" field in the JWT. You can add multiple
          # audiences to accept JWTs from multiple clients.
          - "echo.endpoints.sample.google.com"
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authenication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_id_token:
          audiences:
          # Your OAuth2 client's Client ID must be added here. You can add
          # multiple client IDs to accept tokens from multiple clients.
          - "YOUR-CLIENT-ID"

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"
  authInfoResponse:
    properties:
      id:
        type: "string"
      email:
        type: "string"

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
  # This section configures authentication using Google API Service Accounts
  # to sign a json web token. This is mostly used for server-to-server
  # communication.
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # This must match the 'iss' field in the JWT.
    x-google-issuer: "jwt-client.endpoints.sample.google.com"
    # Update this with your service account's email address.
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR-SERVICE-ACCOUNT-EMAIL"
  # This section configures authentication using Google OAuth2 ID Tokens.
  # ID Tokens can be obtained using OAuth2 clients, and can be used to access
  # your API on behalf of a particular user.
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"

host フィールドのある行で、YOUR_PROJECT_ID を Google Cloud プロジェクト ID に置き換えます。

OpenAPI 3.x

OpenAPI 3.x 仕様を使用して Endpoints を構成するには、ダウンロードしたサンプルコードの dotnet-docs-samples-master\endpoints\getting-started ディレクトリにある openapi-appengine.yaml ファイルの内容を置き換えます。

テキストエディタで openapi-appengine.yaml を開き、内容を次のように置き換えます。

openapi: 3.0.4
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
servers:
  - url: "https://YOUR_PROJECT_ID.appspot.com"
    x-google-endpoint: {}
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      requestBody:
        description: "Message to echo"
        required: true
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/echoMessage"
      responses:
        "200":
          description: "Echo"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/echoMessage"
      security:
        - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      responses:
        "200":
          description: "Authenication info."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/authInfoResponse"
      security:
        - google_jwt: []
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      responses:
        "200":
          description: "Authenication info."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/authInfoResponse"
      security:
        - google_id_token: []

components:
  schemas:
    echoMessage:
      type: "object"
      properties:
        message:
          type: "string"
    authInfoResponse:
      type: "object"
      properties:
        id:
          type: "string"
        email:
          type: "string"

  securitySchemes:
    # This section configures basic authentication with an API key.
    api_key:
      type: apiKey
      name: key
      in: query
    # This section configures authentication using Google API Service Accounts
    # to sign a json web token. This is mostly used for server-to-server
    # communication.
    google_jwt:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "jwt-client.endpoints.sample.google.com"
        jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
        audiences:
          - "echo.endpoints.sample.google.com"
        # This must match the "aud" field in the JWT. You can add multiple
        # audiences to accept JWTs from multiple clients.
    # This section configures authentication using Google OAuth2 ID Tokens.
    # ID Tokens can be obtained using OAuth2 clients, and can be used to access
    # your API on behalf of a particular user.
    google_id_token:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "https://accounts.google.com"
        jwksUri: "https://www.googleapis.com/oauth2/v1/certs"
        audiences:
          - "YOUR_CLIENT_ID"

openapi.yaml の新しい内容を保存します。

このチュートリアルでは、サービス名を構成できる OpenAPI 仕様の Google 固有の拡張機能を使用します。サービス名を指定する方法は、使用している OpenAPI 仕様のバージョンによって異なります。

OpenAPI 2.0

host フィールドを使用して、サービス名を指定します。

host: YOUR_PROJECT_ID.appspot.com

Endpoints を構成するには:

openapi-appengine.yaml ファイルを開きます。
host フィールドで、YOUR_PROJECT_ID を Google Cloud プロジェクト ID に置き換えます。
openapi-appengine.yaml ファイルを保存します。

OpenAPI 3.x

サービス名を指定するには、servers オブジェクトの url フィールドを使用します。

servers:
- url: https://YOUR_PROJECT_ID.appspot.com
  x-google-endpoint: {}

Endpoints を構成するには:

openapi-appengine.yaml ファイルを開きます。
openapi-appengine.yaml ファイルに host フィールドがある場合は、削除します。
次に示すように、servers オブジェクトを追加します。
url フィールドで、YOUR_PROJECT_ID を Google Cloud プロジェクト ID に置き換えます。
openapi-appengine.yaml ファイルを保存します。

注: サーバーで使用する正しい URL を指定するには、server オブジェクトに x-google-endpoint: {} を含める必要があります。このリストには他のサーバーを含めることができますが、正しいサーバーを指定するには、1 つだけ x-google-endpoint: {} を含める必要があります。他の URL はすべて無視されます。

Endpoints 構成をデプロイする

Endpoints の構成をデプロイするには、gcloud endpoints services deploy コマンドを使用します。このコマンドを実行すると、Service Management を使用してマネージドサービスが作成されます。

Endpoints 構成をデプロイするには:

openapi.yaml 構成ファイルがあるディレクトリにいることを確認します。
構成をアップロードしてマネージドサービスを作成します。
```
gcloud endpoints services deploy openapi.yaml
```

gcloud コマンドが Service Management API を呼び出して、openapi.yaml ファイルの host フィールドまたは servers.url フィールドで指定した名前のマネージドサービスを作成します。Service Management は、openapi.yaml ファイル内の設定に従ってサービスを構成します。openapi.yaml に変更を加えるときは、このファイルを再デプロイして Endpoints サービスを更新する必要があります。

Service Management でサービスの作成と構成が行われるとき、情報がターミナルに出力されます。openapi.yaml ファイル内のパスが API キーを要求していないことを示す警告は無視して問題ありません。サービスの構成が完了すると、Service Management に、次のようなサービス構成 ID とサービス名を含むメッセージが表示されます。

Service Configuration [2017-02-13r0] uploaded for service [example-project-12345.appspot.com]

上記の例では、2017-02-13r0 はサービス構成 ID、example-project-12345.appspot.com は Endpoints サービスです。サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。同じ日に openapi.yaml ファイルを再度デプロイすると、サービス構成 ID のリビジョン番号が増分されます。Endpoints サービスの構成は、 Google Cloud コンソールの [エンドポイント] > [サービス] ページで確認できます。

エラーメッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。

必要なサービスの確認

Endpoints と ESP を使用するには、少なくとも次の Google サービスの有効化が必要です。

名前	タイトル
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

ほとんどの場合、gcloud endpoints services deploy コマンドによってこれらの必須サービスが有効化されます。ただし、以下の状況では、gcloud コマンドは正常に完了しますが、必須サービスが有効になりません。

Terraform などのサードパーティのアプリケーションを使用していて、上記のサービスを含めていない場合。
上記のサービスが明示的に無効にされている既存のGoogle Cloud プロジェクトに Endpoints 構成をデプロイした場合。

必要なサービスが有効になっていることを確認するには、次のコマンドを実行します。

gcloud services list

必要なサービスが表示されない場合は、次のコマンドを使用してサービスを有効にします。

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Endpoints サービスも有効にします。

gcloud services enable ENDPOINTS_SERVICE_NAME

ENDPOINTS_SERVICE_NAME を確認するには、次のいずれかを行います。

Endpoints 構成をデプロイ後、Cloud コンソールの [Endpoints] ページに移動します。[サービス名] 列に、考えられる ENDPOINTS_SERVICE_NAME のリストが表示されます。
OpenAPI の場合、ENDPOINTS_SERVICE_NAME は OpenAPI 仕様の host フィールドで指定したものです。gRPC の場合、ENDPOINTS_SERVICE_NAME は gRPC Endpoints 構成の name フィールドで指定したものです。

gcloud コマンドの詳細については、gcloud サービスをご覧ください。

API バックエンドをデプロイする

ここまでの手順で OpenAPI ドキュメントを Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイしていません。ここでは、サンプル API と ESP を App Engine にデプロイします。

API バックエンドをデプロイするには:

endpoints/getting-started/src/IO.Swagger/app.yaml ファイルを開き、サービス名を追加します。

endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
  # previously run the deploy command, you can list your existing configuration
  # ids using the 'configs list' command as follows:
  # 'gcloud endpoints configs list --service=[PROJECT-ID].appspot.com'
  # where [PROJECT-ID].appspot.com is your Endpoints service name.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

ENDPOINTS-SERVICE-NAME を Endpoints サービスの名前で置き換えます。これは、OpenAPI ドキュメントの host フィールドで構成した名前と同じです。次に例を示します。

endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed

rollout_strategy: managed オプションを指定すると、デプロイ済みの最新のサービス構成を使用するように ESP が構成されます。このオプションを指定すると、新しいサービス構成をデプロイしてから 5 分以内に ESP が変更を検出し、自動的に使用します。ESP が特定の構成 ID でなく、このオプションを使用するようにしてください。

app.yaml ファイルを保存します。

endpoints_api_service セクションが app.yaml ファイルに含まれているため、gcloud app deploy コマンドは ESP を App Engine フレキシブル環境の別のコンテナにデプロイして構成します。すべてのリクエストトラフィックは ESP 経由でルーティングされ、ESP はバックエンドサーバーコードを実行するコンテナとの間でリクエストとレスポンスの送受信を行います。

openapi.yaml 構成ファイルがある endpoints/getting-started ディレクトリにいることを確認します。
サンプル API と ESP を App Engine にデプロイします。
```
  dotnet restore
    dotnet publish
    gcloud app deploy src\IO.Swagger\bin\Debug\netcoreapp2.0\publish\app.yaml
```
gcloud app deploy コマンドは、YOUR_PROJECT_ID.appspot.com という形式の DNS レコードを作成しますが、これは API にリクエストを送信するときに使用します。App Engine が完全に初期化される間、API にリクエストを送信するまで数分待つことをおすすめします。

エラーメッセージが表示された場合は、App Engine フレキシブル環境でのデプロイのトラブルシューティングをご覧ください。

詳しくは、API バックエンドをデプロイするをご覧ください。

API にリクエストを送信する

サンプル API をデプロイしたら、API にリクエストを送信します。

API キーを作成し、環境変数を設定する

サンプルコードには API キーが必要です。リクエストを簡単にするために、API キーの環境変数を設定します。

API に使用したのと同じ Google Cloud プロジェクトの API 認証情報ページで API キーを作成します。別の Google Cloud プロジェクトで API キーを作成する場合は、 Google Cloud プロジェクトで API を有効にするをご覧ください。

[認証情報] ページに移動
[認証情報を作成] をクリックして [API キー] を選択します。
キーをクリップボードにコピーします。
[閉じる] をクリックします。
ローカル PC で、API キーを貼り付けて環境変数に割り当てます。 $Env:ENDPOINTS_KEY="AIza..."

リクエストを送信する

PowerShell で、App Engine プロジェクト URL の環境変数を設定します。YOUR_PROJECT_ID は、実際のGoogle Cloud プロジェクト ID に置き換えます。

$Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

設定済みの ENDPOINTS_HOST 環境変数と ENDPOINTS_KEY 環境変数を使用して、HTTP リクエストをテストします。

Invoke-WebRequest "$ENDPOINTS_HOST/echo?key=$ENDPOINTS_KEY" `
  -Body '{"message": "hello world"}' -Method POST `
  -ContentType "application/json"

上記の例では、最初の 2 行はバッククォートで終わります。この例を PowerShell に貼り付けるとき、バッククォートの後にスペースがないことを確認してください。このリクエスト例で使用されているオプションについては、Microsoft のドキュメントの Invoke-WebRequest をご覧ください。

API によって送信メッセージがエコーバックされ、次のようなレスポンスが返されます。

{
  "message": "hello world"
}

正常なレスポンスが返されなかった場合は、レスポンスエラーのトラブルシューティングをご覧ください。

これで Endpoints の API のデプロイとテストが完了しました。

API の活動を追跡する

[エンドポイント] ページで API のアクティビティグラフを確認します。

[Endpoints] の [サービス] ページに移動

グラフにリクエストが反映されるまでしばらくかかります。
[ログ　エクスプローラ] ページで API のリクエスト　ログを確認します。

[ログエクスプローラ] ページに移動

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

クリーンアップ

このチュートリアルで使用したサービスを停止するには、API と API インスタンスを削除するをご覧ください。

ESP を使用した App Engine フレキシブル環境（.NET）での Cloud Endpoints のスタートガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目標

費用

始める前に

始める前に

サンプルコードの取得

Endpoints を構成する

OpenAPI 2.0

OpenAPI 3.x

OpenAPI 2.0

OpenAPI 3.x

Endpoints 構成をデプロイする

必要なサービスの確認

API バックエンドをデプロイする

API にリクエストを送信する

API キーを作成し、環境変数を設定する

リクエストを送信する

API の活動を追跡する

クリーンアップ

クリーンアップ

次のステップ

ESP を使用した App Engine フレキシブル環境（.NET）での Cloud Endpoints のスタートガイド