ノート:

Oracle Integrationを使用したOracle Cloud Infrastructure API GatewayへのAPIの移行

イントロダクション

Oracle Cloud Infrastructure API Gateway (OCI API Gateway)サービスでは、ネットワーク上のアクセス可能なプライベート・エンドポイントとともに、インターネット・トラフィックを受け入れる場合にパブリックIPアドレスで公開できるAPIを公開できます。エンドポイントは、API検証、リクエストとレスポンスの変換、CORS、認証と認可およびリクエスト制限をサポートします。

OCI APIゲートウェイ・サービスを使用して、APIクライアント・トラフィックを処理し、バックエンド・サービスにルーティングするために、リージョン・サブネットに1つ以上のAPIゲートウェイを作成します。単一のAPIゲートウェイを使用して、複数のバックエンド・サービス(ロード・バランサ、コンピュート・インスタンス、Oracle Cloud Infrastructure Functionsなど)を単一の統合APIエンドポイントにリンクできます。

OCI APIゲートウェイ・サービスにアクセスして、OCIコンソールおよびREST APIを使用してAPIゲートウェイおよびAPIデプロイメントを定義できます。

OCI APIゲートウェイ・サービスは、Oracle Cloud Infrastructure Identity and Access Management (OCI IAM)と統合されており、ネイティブのOracle Cloud Infrastructure (OCI)アイデンティティ機能を簡単に認証できます。

OCI APIゲートウェイでは、JSON構造をインポートすることでAPIデプロイメントを実行できます。ここでは、この構造のAPIデプロイメント仕様の作成の形式を確認できます。

{
  "requestPolicies": {},
  "routes": [
    {
      "path": "<api-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "<backend-type>",
        "<backend-target>": "<identifier>"
      },
      "requestPolicies": {}
    }
  ]
}

コンソールに加えて、Oracle Cloud Infrastructureコマンドライン・インタフェース(OCI CLI)とOCI API GatewayのOCI RESTサービスを使用してAPIをデプロイできます。デプロイ方法を理解するためのドキュメントを次に示します。

標準のOCI API Gateway形式でデプロイするAPI構造がすでにある場合は、コンソール(インポート)、OCI CLIまたはRESTコールを使用して簡単にデプロイできます。この構造を準備しておくと、複数のJSONファイルを処理するコードを簡単に作成できます。次の例では、bashスクリプト・コードを使用してファイルを処理する方法を示します:

#!/bin/bash
# Folder containing JSON files
folder="/<your path to the JSON Files>"
# Loop through the JSON files in the folder
for file in "$folder"/*.json; do
    service="${file##*/}"; service="${service%.*}"
    echo "Service: $service"        # Read and display the contents of the JSON file
    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxx --display-name $service --gateway-id ocid1.apigateway.oc1.iad.xxxxxxxxxxxxxxxxxxxxxxxxxxxx --path-prefix "/$service" --specification file://$file --debug
    echo "-------------------"
done

場合によっては、APIメタデータ情報を処理する必要があります。これは、Python、Javaまたはその他の言語を使用したコードを介して行うことができますが、このチュートリアルの目的は、Oracle Integrationを使用して自動化することです。このように行うにはいくつかの利点があります。次を簡単に実行できます。

目的

前提条件

タスク1: ソースAPIデータ構造の理解

APIメタデータ構造から開始できます。最もよく知られている定義は、OpenAPIまたはSwaggerです。

SWAGGERまたはOpenAPIがある場合は、OCIコンソール、OCI CLIまたはOCI API Gateway RESTサービスでインポートすることで、APIデータをOCI API Gatewayにインポートできます。APIの説明を含むAPIリソースの作成を参照してください。

これらの形式(Swagger/OpenAPI)がない場合は、APIデータ定義を別の形式で構成する必要があります。このタスクでは、Excel構造を使用して、この構造からJSONに変換します。

Excel_api_migration_source.png

そのため、使用するJSON構造があります。

[ {
  "API_NAME" : "cep",
  "TYPE" : "REST",
  "METHOD" : "GET",
  "PATH_PREFIX" : "/okecep",
  "PATH" : "/cep",
  "ENDPOINT" : "http://x.x.x.x/cep",
  "QUERY_PARAMETERS" : "cep",
  "GROOVY_SCRIPT" : "",
  "AUTHENTICATION_TYPE" : "BASIC",
  "ENVIRONMENT" : "QA",
  "HEADER" : "",
  "HEADER_VALUE" : ""
}, {
  "API_NAME" : "calculator",
  "TYPE" : "SOAP",
  "METHOD" : "POST",
  "PATH_PREFIX" : "/dneonline",
  "PATH" : "/calculator",
  "ENDPOINT" : "http://www.example.com/calculator.asmx",
  "QUERY_PARAMETERS" : "",
  "GROOVY_SCRIPT" : "",
  "AUTHENTICATION_TYPE" : "BASIC",
  "ENVIRONMENT" : "DEV",
  "HEADER" : "",
  "HEADER_VALUE" : ""
} ]

これらのAPIデータ構造は、source_apis.jsonにあります。API定義データを任意の形式で構造化できます。これは単なる例です。

タスク2: OCI APIゲートウェイ・デプロイメント・データの理解

このタスクでは、API定義をOCI APIゲートウェイにインポートするためのネイティブ・フォーマットを確認できます。多くの場合、単純な構造はAPIを実装するのに十分ですが、セキュリティ、ヘッダー・ルール、パラメータなどの詳細が表示されるため、JSON構造が大きくなります。これは、あらゆるタイプのデプロイメントの完全なJSON構造になります。これをOracle Integrationのフローで使用します。ファイルは apigw_structure.jsonにあります。

{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "tokenHeader": "",
      "tokenQueryParam": "",
      "tokenAuthScheme": "authentication-scheme",
      "isAnonymousAccessAllowed": false,
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "maxClockSkewInSeconds": 0,
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "client-id",
          "clientSecretId": "secret-ocid",
          "clientSecretVersionNumber": 0
        },
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "well-known-uri"
        },
        "isSslVerifyDisabled": true,
        "maxCacheDurationInHours": 0,
        "additionalValidationPolicy": {
          "issuers": ["issuer-url", "issuer-url"],
          "audiences": ["intended-audience"],
          "verifyClaims": [{
            "key": "claim-name",
            "values": ["acceptable-value", "acceptable-value"],
            "isRequired": true
          }]
        }
      },
      "tokenHeader": "Authorization",
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1",
          "clientSecretId": "ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q",
          "clientSecretVersionNumber": 1
        },
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "https://my-idp/oauth2/default/.well-known/openid-configuration"
        },
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    },
    "mutualTls":{
      "isVerifiedCertificateRequired": true,
      "allowedSans": ["api.weather.com"]
    }
  },
  "routes": [
    {
      "path": "/weather",
      "methods": ["GET"],
      "backend": {
        "type": "HTTP_BACKEND",
        "url": "https://api.weather.gov/${request.auth[region]}"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "weatherwatcher" ]
        },
        "headerValidations": {
          "headers": {
            "name": "header-name",
            "required": true
          },
          "validationMode": "ENFORCING|PERMISSIVE|DISABLED"
        },
        "queryParameterValidations": {
          "parameters": {
            "name": "query-parameter-name",
            "required": true
          },
          "validationMode": "ENFORCING|PERMISSIVE|DISABLED"
        },
        "bodyValidation": {
          "required": true,
          "content": {
            "media-type-1": {
              "validationType": "NONE"
            },
            "media-type-2": {
              "validationType": "NONE"
            }
          },
          "validationMode": "ENFORCING|PERMISSIVE|DISABLED"
        },
        "headerTransformations": {
          "renameHeaders": {
            "items": [
              {
                "from": "original-name",
                "to": "new-name"
              }
            ]
          },
          "setHeaders": {
            "items": [
              {
                "name": "header-name",
                "values": ["header-value"],
                "ifExists": "OVERWRITE|APPEND|SKIP"
              }
            ]
          }
        },
        "queryParameterTransformations": {
          "filterQueryParameters": {
            "type": "BLOCK|ALLOW",
            "items": [
              {
                "name": "query-parameter-name"
              }
            ]
          },
          "renameQueryParameters": {
            "items": [
              {
                "from": "original-name",
                "to": "new-name"
              }
            ]
          },
          "setQueryParameters": {
            "items": [
              {
                "name": "query-parameter-name",
                "values": ["query-parameter-value"],
                "ifExists": "OVERWRITE|APPEND|SKIP"
              }
            ]
          }
        }
      },
      "responsePolicies": {
        "headerTransformations": {
          "filterHeaders": {
            "type": "BLOCK|ALLOW",
            "items": [
              {
                "name": "header-name"
              }
            ]
          },
          "renameHeaders": {
            "items": [
              {
                "from": "original-name",
                "to": "new-name"
              }
            ]
          },
          "setHeaders": {
            "items": [
              {
                "name": "header-name",
                "values": ["header-value"],
                "ifExists": "OVERWRITE|APPEND|SKIP"
              }
            ]
          }
        }
      }
    }
  ]
}

タスク3: 接続の作成

作成する必要がある接続は2つあります。最初の接続は、トリガーREST接続です。この接続は、Oracle Integrationでエンドポイントを公開するために使用されます。このエンドポイントでは、移行プロセスをRESTサービスとしてコールし、APIのソース・データを渡すことができます。

2番目の接続は、OCI API Gateway RESTサービスをコールしてAPIデプロイメントを作成するために使用されます。OCI API Gateway RESTドキュメントは、RESTを介したAPIのデプロイを参照してください。

Oracle Integration接続を作成します。REST接続の作成を参照してください。

  1. RESTアダプタを検索します。

    connection_rest_1.png

  2. 名前と識別子を指定します。たとえば、"REST_EXPOSE"という名前を付けます。これが最初の接続です。「トリガー・ロール」を選択します。トリガー・ロールは、接続をRESTエンドポイントとして公開し、「作成」をクリックすることを意味します。

    Connection_Rest_2.png

  3. トリガー・エンドポイントでは、Oracle Integration Basic認証を使用してリクエストを実行できます。そのため、ユーザー名とパスワードを使用できます。

    Connect_Rest_3.png

  4. 2番目の接続では、最初の接続で行ったように、名前と識別子(たとえば、APIGW_REST_API)を指定します。最初の構成とは異なり、必ず「Invoke」タイプを選択してください。リージョンに適したOCI APIゲートウェイRESTを選択します(この例では、リージョンはアッシュバーンです)。リージョンOCI APIゲートウェイ・エンドポイントの適切なエンドポイントを表示するには、ここを参照してください。OCI資格証明を取得して、OCI APIゲートウェイ・サービスへのアクセスを提供します。

    Connection_Apigateway_Rest_Api.png

タスク4: 統合の作成

APIソース・メタデータをOCI APIゲートウェイに移行するプロセスは次のとおりです:

  1. 前に作成したトリガーREST接続との統合を公開します。

    Integration_1.png

  2. リクエスト・エンドポイントの名前を指定します。

    Integration_1a.png

  3. パス(/convertなど)を指定し、POSTメソッドを選択します。リクエスト・ペイロードを必ず確立してください。

    Integration_1b.png

  4. これで、「JSONサンプル」を選択し、JSONソース構造を貼り付けることができます。

    Integration_1c.png

  5. JSONをここに貼り付けます。

    Integration_1d.png

  6. 次に、APIゲートウェイ・インスタンスの変数を初期化します(各環境は新しいAPIゲートウェイ・インスタンスです)。METHODの変数を作成します。RESTではいくつかのメソッド(GET、POST、PUT、DELETE、ANY)を使用でき、SOAPサービスではPOSTを使用する必要があることに注意してください。

    Integration_2.png

    Integration_2a.png

  7. FOR EACHループを作成します。これにより、ソースJSONリストが処理されます。

    Integration_3.png

  8. For Eachアクションを編集し、ループ・レベル配列を繰返し要素属性にドラッグ・アンド・ドロップします。

    Integration_3a.png

  9. 次に、環境のリダイレクションを構成します。スイッチ・アクションを作成し、各条件のIFおよび割当てを配置します。

    Integration_4.png

  10. QA環境の最初の条件を作成します。

    Integration_4a.png

  11. ソース・メタデータENVIRONMENT属性を確認し、QA値があるかどうかをテストします。

    Integration_4b.png

  12. 条件がtrueの場合は、適切な環境を割り当てる必要があります。GatewayIDおよびCompartmentIDはOCID値です。変数に正しいIDを割り当てる必要があります。

    Integration_4c.png

  13. 他の環境でも同じことをします。

    Integration_5.png

  14. 次に、APIがRESTサービスかSOAPサービスかを確認します。APIがSOAPサービスの場合、メソッドをPOSTとして構成する必要があります。

    Integration_5a.png

  15. サービス・タイプをテストするIF条件を作成します。

    Integration_5b.png

  16. POST値をメソッド変数に割り当てます。

    Integration_5c.png

    Integration_5d.png

  17. 他の状況では、ソース属性は正しいメソッドを提供します。

    Integration_5e.png

    Integration_5f.png

  18. ソース・メタデータ属性をOCI APIゲートウェイ・パラメータにマップします。マッピング・アクションの前に、OCI APIゲートウェイRESTアダプタを構成する必要があります。

    Integration_6.png

  19. 接続を構成します。

    Integration_6a.png

  20. このサービスの名前を指定します。パスは/deploymentsで、メソッドはPOSTである必要があります。必ずリクエスト・ペイロードを構成してください。

    Integration_6b.png

  21. サイズが大きいため、JSON OCI APIゲートウェイ構造を貼り付けることはできません。そのため、コンテンツを含むファイルをアップロードする必要があります。完全なJSON構造は、apigw_structure.JSONにあります。

    Integration_6c.png

  22. ターゲット・メタデータをマップします。

    Integration_6d.png

ノート: Oracle Integrationアーティファクトは、Oracle Integration: OCI APIゲートウェイへのソースAPIの移行で確認できます。このアーティファクトの例は、移行の最終プロセスとして使用することを意図しておらず、プロセスを示す目的のみを持ちます。このアーティファクトを使用して、実際の実装をガイドします。

タスク5: 移行のテスト

詳細は、次のリンクを参照し、次のステップに従います。

  1. ソースJSONデータを追加します。

    Test_1.png

  2. 「テスト」をクリックし、終了するまで待ちます。

    Test_1a.png

  3. OCI APIゲートウェイ・インスタンスのデプロイメントに移動し、APIの作成を確認します。

    Test_2.png

確認

その他の学習リソース

docs.oracle.com/learnの他のラボをご覧いただくか、Oracle Learning YouTubeチャネルで無料のラーニング・コンテンツにアクセスしてください。また、education.oracle.com/learning-explorerにアクセスしてOracle Learning Explorerになります。

製品ドキュメントは、Oracle Help Centerを参照してください。