第2章 サービスの管理
2.1. OpenAPI サービスの設定
OpenAPI 仕様 (OAS) は、HTTP API 向けに、プログラミング言語に依存しない、標準のインターフェイスを定義します。ソースコード、追加のドキュメント、またはネットワークトラフィックの検査にアクセスしなくても、サービスの機能を理解することができます。OpenAPI を使用してサービスを定義すると、最小限の実装ロジックを使用してサービスを理解し、操作することができます。インターフェイスの記述によって低レベルのプログラミングが簡素化されるのと同様に、OpenAPI 仕様 によってサービス呼び出し時の推測作業がなくなります。
2.1.1. OpenAPI 関数定義
OpenShift Serverless Logic を使用すると、ワークフローは関数内の OpenAPI 仕様参照を使用してリモートサービスと対話できます。
OpenAPI 関数定義の例
{ "functions": [ { "name": "myFunction1", "operation": "classpath:/myopenapi-file.yaml#myFunction1" } ] }
operation
属性は、次のパラメーターで構成される string
です。
-
URI
: エンジンはこれを使用して、classpath
などの仕様ファイルを検索します。 - Operation identifier: この識別子は OpenAPI 仕様ファイルにあります。
OpenShift Serverless Logic は以下の URI スキームをサポートします。
-
classpath: アプリケーションプロジェクトの
src/main/resources
フォルダーにあるファイルに使用します。classpath
はデフォルトの URI スキームです。URI スキームを定義しない場合、ファイルの場所はsrc/main/resources/myopenapifile.yaml
になります。 - file: ファイルシステム内にあるファイルに使用します。
- http または https: リモートにあるファイルに使用します。
ビルド時に OpenAPI 仕様ファイルが利用可能であることを確認します。OpenShift Serverless Logic は、実行時にリクエストを送信するために内部コード生成機能を使用します。アプリケーションイメージのビルド後、OpenShift Serverless Logic はこれらのファイルにアクセスできません。
ワークフローに追加する OpenAPI サービスに仕様ファイルがない場合は、仕様ファイルを作成するか、サービスを更新してファイルを生成して公開できます。
2.1.2. OpenAPI 仕様に基づく REST リクエストの送信
OpenAPI 仕様ファイルに基づく REST リクエストを送信するには、次の手順を実行する必要があります。
- 関数参照を定義する
- ワークフロー状態で定義された関数にアクセスする
前提条件
- OpenShift Serverless Logic Operator がクラスターにインストールされている。
- OpenShift Container Platform でアプリケーションやその他のワークロードを作成するための適切なロールと権限を持つ OpenShift Serverless Logic プロジェクトにアクセスできる。
- OpenAPI 仕様ファイルにアクセスできる。
手順
OpenAPI 関数を定義するには、以下を行います。
- 呼び出す予定のサービスの OpenAPI 仕様ファイルを識別してアクセスします。
OpenAPI 仕様ファイルを
src/main/resources/specs
などのワークフローサービスディレクトリーにコピーします。次の例は、乗算 REST サービスの OpenAPI 仕様を示しています。
乗算 REST サービス OpenAPI 仕様の例
openapi: 3.0.3 info: title: Generated API version: "1.0" paths: /: post: operationId: doOperation parameters: - in: header name: notUsed schema: type: string required: false requestBody: content: application/json: schema: $ref: '#/components/schemas/MultiplicationOperation' responses: "200": description: OK content: application/json: schema: type: object properties: product: format: float type: number components: schemas: MultiplicationOperation: type: object properties: leftElement: format: float type: number rightElement: format: float type: number
ワークフローで関数を定義するには、OpenAPI 仕様の
operationId
を使用して、関数定義内の目的の操作を参照します。温度変換アプリケーションにおける関数定義の例
{ "functions": [ { "name": "multiplication", "operation": "specs/multiplication.yaml#doOperation" }, { "name": "subtraction", "operation": "specs/subtraction.yaml#doOperation" } ] }
-
関数定義が
src/main/resources/specs
ディレクトリーに保存されている OpenAPI ファイルへの正しいパスを参照していることを確認します。
ワークフロー状態で定義された関数にアクセスします。
- 追加した関数定義を呼び出すワークフローアクションを定義します。各アクションが以前に定義された関数を参照していることを確認します。
特定の関数を名前で参照するには、
functionRef
属性を使用します。OpenAPI 仕様で定義されたパラメーターを使用して、functionRef
内の引数をマップします。次の例は、リクエスト本文ではなくリクエストパス内のパラメーターのマッピングを示しています。次の PetStore API の例を参照できます。
ワークフローで関数引数をマッピングする例
{ "states": [ { "name": "SetConstants", "type": "inject", "data": { "subtractValue": 32.0, "multiplyValue": 0.5556 }, "transition": "Computation" }, { "name": "Computation", "actionMode": "sequential", "type": "operation", "actions": [ { "name": "subtract", "functionRef": { "refName": "subtraction", "arguments": { "leftElement": ".fahrenheit", "rightElement": ".subtractValue" } } }, { "name": "multiply", "functionRef": { "refName": "multiplication", "arguments": { "leftElement": ".difference", "rightElement": ".multiplyValue" } } } ], "end": { "terminate": true } } ] }
-
リクエスト内のパラメーターの構造化方法を理解するには、OpenAPI 仕様の
Operation Object
のセクションを確認してください。 -
jq
式を使用してペイロードからデータを抽出し、必要なパラメーターにマップします。エンジンが OpenAPI 仕様に従ってパラメーター名をマッピングしていることを確認します。 本文ではなくリクエストパス内のパラメーターを必要とする操作については、OpenAPI 仕様のパラメーター定義を参照してください。
リクエスト本文ではなくリクエストパスでパラメーターをマッピングする方法の詳細は、次の PetStore API の例を参照してください。
パスパラメーターのマッピングの例
{ "/pet/{petId}": { "get": { "tags": ["pet"], "summary": "Find pet by ID", "description": "Returns a single pet", "operationId": "getPetById", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet to return", "required": true, "schema": { "type": "integer", "format": "int64" } } ] } } }
以下は関数の呼び出し例です。リクエストパスに
petId
という名前のパラメーターが 1 つだけ追加されています。PetStore 関数の呼び出し例
{ "name": "CallPetStore", 1 "actionMode": "sequential", "type": "operation", "actions": [ { "name": "getPet", "functionRef": { "refName": "getPetById", 2 "arguments": { 3 "petId": ".petId" } } } ] }
2.1.3. OpenAPI サービスのエンドポイント URL の設定
ワークフロー状態の関数定義にアクセスした後、OpenAPI サービスのエンドポイント URL を設定できます。
前提条件
- OpenShift Container Platform でアプリケーションやその他のワークロードを作成するための適切なロールと権限を持つ OpenShift Serverless Logic プロジェクトにアクセスできる。
- OpenShift Serverless Logic プロジェクトを作成している。
- OpenAPI 仕様ファイルにアクセスできる。
- ワークフローで関数定義を定義している。
- ワークフロー状態で定義された関数にアクセスできる。
手順
-
設定する OpenAPI 仕様ファイルを見つけます。例:
substraction.yaml
-
.
などの特殊文字をアンダースコアに置き換え、文字を小文字に変換して、ファイル名を有効な設定キーに変換します。たとえば、substraction.yaml
をsubstraction_yaml
に変更します。 設定キーを定義するには、変換されたファイル名を REST クライアント設定キーとして使用します。次の例に示すように、このキーを環境変数として設定します。
quarkus.rest-client.subtraction_yaml.url=http://myserver.com
application.properties
ファイルで URL がハードコーディングされるのを防ぐには、次の例に示すように、環境変数の置換を使用します。quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}
この例では、以下が適用されます。
-
Configuration Key:
quarkus.rest-client.subtraction_yaml.url
- 環境変数: SUBTRACTION_URL
-
フォールバック URL:
http://myserver.com
-
Configuration Key:
-
システムまたはデプロイメント環境で
(SUBTRACTION_URL)
環境変数が設定されていることを確認します。変数が見つからない場合、アプリケーションはフォールバック URL(http://myserver.com)
を使用します。 設定キーと URL 置換を
application.properties
ファイルに追加します。quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}
- アプリケーションをデプロイまたは再起動して、新しい設定を適用します。