第2章 サービスの管理

手順

1. OpenAPI 関数を定義するには、以下を行います。

   1. 呼び出す予定のサービスの OpenAPI 仕様ファイルを識別してアクセスします。

   2. 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

   3. ワークフローで関数を定義するには、OpenAPI 仕様の operationId を使用して、関数定義内の目的の操作を参照します。

      温度変換アプリケーションにおける関数定義の例

      {
         "functions": [
           {
             "name": "multiplication",
             "operation": "specs/multiplication.yaml#doOperation"
           },
           {
             "name": "subtraction",
             "operation": "specs/subtraction.yaml#doOperation"
           }
         ]
      }

   4. 関数定義が src/main/resources/specs ディレクトリーに保存されている OpenAPI ファイルへの正しいパスを参照していることを確認します。

2. ワークフロー状態で定義された関数にアクセスします。

   1. 追加した関数定義を呼び出すワークフローアクションを定義します。各アクションが以前に定義された関数を参照していることを確認します。

   2. 特定の関数を名前で参照するには、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
            }
          }
        ]
      }

   3. リクエスト内のパラメーターの構造化方法を理解するには、OpenAPI 仕様の Operation Object のセクションを確認してください。
   4. jq 式を使用してペイロードからデータを抽出し、必要なパラメーターにマップします。エンジンが OpenAPI 仕様に従ってパラメーター名をマッピングしていることを確認します。

   5. 本文ではなくリクエストパス内のパラメーターを必要とする操作については、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"
              }
            }
          }
        ]
      }

      1

      CallPetStore などの状態定義。

      2

      関数定義リファレンス。前述の例では、関数定義 getPetById は PetStore OpenAPI 仕様用です。

      3

      引数の定義。OpenShift Serverless Logic は、リクエストを送信する前に、petId 引数をリクエストパスに追加します。

手順

1. 設定する OpenAPI 仕様ファイルを見つけます。例: substraction.yaml
2. . などの特殊文字をアンダースコアに置き換え、文字を小文字に変換して、ファイル名を有効な設定キーに変換します。たとえば、substraction.yaml を substraction_yaml に変更します。

3. 設定キーを定義するには、変換されたファイル名を REST クライアント設定キーとして使用します。次の例に示すように、このキーを環境変数として設定します。

   quarkus.rest-client.subtraction_yaml.url=http://myserver.com

4. 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
5. システムまたはデプロイメント環境で (SUBTRACTION_URL) 環境変数が設定されていることを確認します。変数が見つからない場合、アプリケーションはフォールバック URL (http://myserver.com) を使用します。

6. 設定キーと URL 置換を application.properties ファイルに追加します。

   quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}

7. アプリケーションをデプロイまたは再起動して、新しい設定を適用します。