Oracle Cloud Infrastructureドキュメント

APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイ

APIゲートウェイ・サービスを使用してAPIデプロイメントを作成し、APIゲートウェイにAPIデプロイする方法をご紹介します。

APIゲートウェイを作成したら、APIデプロイメントを作成して、APIゲートウェイにAPIをデプロイします。APIデプロイメントを作成するときは、APIを定義するAPIデプロイメント仕様を含めます。APIゲートウェイ・サービスはAPIデプロイメント仕様を検査して、有効であることを確認します。

次を実行して、単一APIゲートウェイを複数のバックエンド・サービスのフロント・エンドとして使用できます:

  • 複数のバックエンド・サービスを定義するAPIデプロイメント仕様を使用してAPIゲートウェイで単一のAPIデプロイメントを作成します。
  • それぞれに1つ(または、それ以上)のバックエンド・サービスを定義するAPIデプロイメント仕様を使用して、同じAPIゲートウェイに複数のAPIデプロイメントを作成します。

コンソールを使用してAPIデプロイメントを最初から作成

コンソールを使用してAPIデプロイメントを作成するには、次に示すように、コンソールのダイアログでAPIデプロイメント仕様を入力します:

  1. 「ゲートウェイ」リスト・ページで、APIをデプロイするAPIゲートウェイを選択します。リスト・ページまたはAPIゲートウェイの検索に関するヘルプが必要な場合は、APIゲートウェイのリストを参照してください。
  2. 「Gateway Details」ページで、「Resources」リストから「Deployments」を選択し、「Create Deployment」を選択します。

  3. 「最初から」を選択し、「基本情報」セクションで次を指定します:

    • 名前:新しいAPIデプロイメントの名前。機密情報の入力は避けてください。

    • パス接頭辞: APIデプロイメント仕様に含まれるすべてのルートをデプロイするパス。例:

      • /v1
      • /v2
      • /test/20191122

      指定するデプロイメント・パス接頭辞は、次の点に注意してください:

      • 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
      • スラッシュは複数使用できますが(隣接していない場合)、スラッシュで終了しないでください
      • 英数字の大文字と小文字を使用できます
      • 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
      • パラメータおよびワイルドカードを含めることはできません

      また、APIデプロイメントのデプロイメント・パス接頭辞として1つのフォワード・スラッシュがある場合、それは特定のAPIゲートウェイで許可される唯一のAPIデプロイメントです。同じAPIゲートウェイに別のAPIデプロイメントがすでに存在する場合、デプロイメント・パス接頭辞として単一のフォワード・スラッシュを使用してAPIデプロイメントを作成することはできません。

    • コンパートメント: 新規APIデプロイメントを作成するコンパートメント。

  4. (オプション)「APIリクエスト・ポリシー」セクションで、次のサポートを提供するリクエスト・ポリシー詳細をオプションで指定します:

  5. (オプション)「APIロギング・ポリシー」セクションで、APIゲートウェイ内の処理に関する情報を記録する実行ログ・レベルをオプションで指定します。APIデプロイメントへのロギングの追加を参照してください。

  6. (オプション)「拡張オプションの表示」を選択し、オプションで次を指定します:

    • タグ: リソースの作成権限がある場合は、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済のタグを適用するには、タグ・ネームスペースを使用する権限が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかがわからない場合は、このオプションをスキップするか、管理者に問い合せてください。タグは後で適用できます。
  7. 「次」を選択して「認証」ページを表示し、認証リクエスト・ポリシーの詳細を入力します:

    詳細は、「APIデプロイメントへの認証と認可の追加」を参照してください。

  8. 「次」を選択して、APIデプロイメントのルートの詳細を入力します。

  9. 「ルート1」セクションで、1つのパスと1つ以上のメソッドをバックエンド・サービスにマップするAPIデプロイメントの最初のルートを指定します:

    • パス: リストされたメソッドを使用したバックエンド・サービスへのAPIコールのパス。指定するルート・パスで次の点に注意してください:

      • デプロイメント・パス接頭辞に対して相対的です
      • 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
      • スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
      • 英数字の大文字と小文字を使用できます
      • 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
      • パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
    • メソッド: バックエンド・サービスが受け入れる1つ以上のメソッド(カンマ区切り)。たとえば、GET, PUTです。

    • 単一のバックエンドの追加または複数のバックエンドの追加: すべてのリクエストを同じバックエンドにルーティングするか、入力したコンテキスト変数およびルールに従ってリクエストを異なるバックエンドにルーティングするか。

      これらの手順では、単一のバックエンドを使用することを想定しているため、「単一のバックエンドの追加」を選択します。または、異なるバック・エンドを使用する場合は、「複数のバックエンドの追加」を選択し、コンソールを使用したAPIデプロイメント仕様への動的バック・エンド選択の追加の手順に従います。

    • バックエンド・タイプ:バックエンド・サービスのタイプ。次のいずれかです:
  10. (オプション)「別のルート」を選択して、追加ルートの詳細を入力します。
  11. 「次」を選択して、新しいAPIデプロイメント用に入力した詳細を確認します。

  12. 「作成」を選択して、新しいAPIデプロイメントを作成します。

    新しいAPIデプロイメントの作成には数分かかる場合があります。作成中のAPIデプロイメントは、「ゲートウェイの詳細」ページに作成中の状態で表示されます。正常に作成されると、新規APIデプロイメントがアクティブの状態で表示されます。

    また、新しいAPIデプロイメントをすぐに作成するかわりに、リソース・マネージャおよびTerraformを使用して後で作成するには、「スタックとして保存」を選択してリソース定義をTerraform構成として保存します。リソース定義からのスタックの保存の詳細は、「リソース作成ページからのスタックの作成」を参照してください。

  13. APIデプロイメントがアクティブの状態で表示されるのを数分以上待機していた場合(またはAPIデプロイメント作成操作に失敗した場合):

    1. APIデプロイメントの名前を選択し、「作業リクエスト」を選択してAPIデプロイメント作成操作の概要を表示します。
    2. 「デプロイメントの作成」操作を選択して、操作に関する詳細情報(エラー・メッセージ、ログ・メッセージ、関連付けられたリソースのステータスなど)を表示します。
    3. APIデプロイメントの作成操作が失敗したため、作業リクエスト情報から問題の原因を診断できない場合は、APIゲートウェイのトラブルシューティングを参照してください。
  14. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

コンソールを使用したJSONファイルからのAPIデプロイメントの作成

コンソールを使用してAPIデプロイメントを作成するには、JSONファイルからAPIデプロイメント仕様をアップロードします:

  1. 「ゲートウェイ」リスト・ページで、APIをデプロイするAPIゲートウェイを選択します。リスト・ページまたはAPIゲートウェイの検索に関するヘルプが必要な場合は、APIゲートウェイのリストを参照してください。
  2. 「Gateway Details」ページで、「Resources」リストから「Deployments」を選択し、「Create Deployment」を選択します。
  3. 「既存のAPIのアップロード」を選択します。

  4. 「アップロード情報」セクションで、次を指定します:

    • 名前:新しいAPIデプロイメントの名前。機密情報の入力は避けてください。

    • パス接頭辞: APIデプロイメント仕様に含まれるすべてのルートをデプロイするパス。例:

      • /v1
      • /v2
      • /test/20191122

      指定するデプロイメント・パス接頭辞は、次の点に注意してください:

      • 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
      • スラッシュは複数使用できますが(隣接していない場合)、スラッシュで終了しないでください
      • 英数字の大文字と小文字を使用できます
      • 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
      • パラメータおよびワイルドカードを含めることはできません
    • コンパートメント: 新規APIデプロイメントを作成するコンパートメント。
    • 仕様:ファイルをドラッグ・アンド・ドロップするか、または「1つを選択」を選択することによる、APIデプロイメント仕様を含むJSONファイル。APIデプロイメント仕様の作成を参照してください。

    また、APIデプロイメントのデプロイメント・パス接頭辞として1つのフォワード・スラッシュがある場合、それは特定のAPIゲートウェイで許可される唯一のAPIデプロイメントです。同じAPIゲートウェイに別のAPIデプロイメントがすでに存在する場合、デプロイメント・パス接頭辞として単一のフォワード・スラッシュを使用してAPIデプロイメントを作成することはできません。

  5. (オプション)「拡張オプションの表示」を選択し、オプションで次を指定します:

    • タグ: リソースの作成権限がある場合は、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済のタグを適用するには、タグ・ネームスペースを使用する権限が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかがわからない場合は、このオプションをスキップするか、管理者に問い合せてください。タグは後で適用できます。
  6. 「次」を選択して、新しいAPIデプロイメント用に入力した詳細を確認します。

  7. 「作成」を選択して、新しいAPIデプロイメントを作成します。

    新しいAPIデプロイメントの作成には数分かかる場合があります。作成中のAPIデプロイメントは、「ゲートウェイの詳細」ページに作成中の状態で表示されます。正常に作成されると、新規APIデプロイメントがアクティブの状態で表示されます。

    また、新しいAPIデプロイメントをすぐに作成するかわりに、リソース・マネージャおよびTerraformを使用して後で作成するには、「スタックとして保存」を選択してリソース定義をTerraform構成として保存します。リソース定義からのスタックの保存の詳細は、「リソース作成ページからのスタックの作成」を参照してください。

  8. APIデプロイメントがアクティブの状態で表示されるのを数分以上待機していた場合(またはAPIデプロイメント作成操作に失敗した場合):

    1. APIデプロイメントの名前を選択し、「作業リクエスト」を選択してAPIデプロイメント作成操作の概要を表示します。
    2. 「デプロイメントの作成」操作を選択して、操作に関する詳細情報(エラー・メッセージ、ログ・メッセージ、関連付けられたリソースのステータスなど)を表示します。
    3. APIデプロイメントの作成操作が失敗したため、作業リクエスト情報から問題の原因を診断できない場合は、APIゲートウェイのトラブルシューティングを参照してください。
  9. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

コンソールを使用したAPIリソースからのAPIデプロイメントの作成

APIリソースのAPI記述を使用して、既存のAPIリソースからAPIデプロイメントを作成できます。この場合、API記述は、APIリソース用にアップロードしたAPI記述ファイルに基づいています(API記述を含めたAPIリソースの作成を参照)。API記述ファイルにはAPIデプロイメント仕様の初期値がいくつか用意されていますが、これはAPIデプロイメントの作成時に変更および拡張できます。具体的には、API記述内のパスおよび関連メソッドごとにデフォルト・ルートが作成されます。

コンソールで、API記述ファイルから導出されたAPIデプロイメント仕様を使用して既存のAPIリソースからAPIデプロイメントを作成するには:

  1. 「API」リスト・ページで、デプロイするAPIリソースの名前を選択します。リスト・ページの検索に関するヘルプが必要な場合は、APIリソースのリストを参照してください。
  2. (オプション)「APIの詳細」ページで、「リソース」リストから「APIデプロイメント仕様」を選択して、アップロードしたAPI記述ファイルからAPIリソースに有効なAPIデプロイメント仕様が作成されていることを確認します。使用可能なAPIデプロイメント仕様がない場合は、API記述を含めたAPIリソースの作成を参照してください
  3. 「API詳細」ページで、APIデプロイメントを作成するためのコンソール・ダイアログを使用するには、「APIゲートウェイのデプロイ」を選択します。

    コンソールの各ダイアログに表示されるAPIデプロイメント仕様プロパティの初期値の一部は、API記述ファイルから導出されます。

    「API情報」セクションには、APIデプロイメントの作成元のAPIリソースの詳細が表示されます。

  4. 「ゲートウェイ」セクションで、APIデプロイメントを作成するAPIゲートウェイを選択します。適切なAPIゲートウェイがまだ存在していない場合は、「ゲートウェイの作成」を選択し、それを作成します(APIゲートウェイの作成を参照)。

  5. 「基本情報」セクションで、次を指定します:

    • 名前:新しいAPIデプロイメントの名前。機密情報の入力は避けてください。

    • パス接頭辞: APIデプロイメント仕様に含まれるすべてのルートをデプロイするパス。

      例:

      • /v1
      • /v2
      • /test/20191122

      指定するデプロイメント・パス接頭辞は、次の点に注意してください:

      • 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
      • スラッシュは複数使用できますが(隣接していない場合)、スラッシュで終了しないでください
      • 英数字の大文字と小文字を使用できます
      • 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
      • パラメータおよびワイルドカードを含めることはできません

      また、APIデプロイメントのデプロイメント・パス接頭辞として1つのフォワード・スラッシュがある場合、それは特定のAPIゲートウェイで許可される唯一のAPIデプロイメントです。同じAPIゲートウェイに別のAPIデプロイメントがすでに存在する場合、デプロイメント・パス接頭辞として単一のフォワード・スラッシュを使用してAPIデプロイメントを作成することはできません。

    • コンパートメント: 新規APIデプロイメントを作成するコンパートメント。

  6. (オプション)「APIリクエスト・ポリシー」セクションで、次のサポートを提供するリクエスト・ポリシー詳細をオプションで指定します:

  7. (オプション)「APIロギング・ポリシー」セクションで、APIゲートウェイ内の処理に関する情報を記録する実行ログ・レベルをオプションで指定します。APIデプロイメントへのロギングの追加を参照してください。

  8. (オプション)「拡張オプションの表示」を選択し、オプションで次を指定します:

    • タグ: リソースの作成権限がある場合は、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済のタグを適用するには、タグ・ネームスペースを使用する権限が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかがわからない場合は、このオプションをスキップするか、管理者に問い合せてください。タグは後で適用できます。

  9. 「次」を選択し、APIデプロイメントのルートの詳細を確認して入力します。

    デフォルトでは、API記述に存在するすべてのパスおよび関連メソッドに対してルートが作成されます。最初は、これらの各デフォルト・ルートは標準レスポンス・バックエンドを使用して作成されます。HTTPステータス・コード、レスポンス本文のコンテンツ、およびヘッダーは、API記述の詳細から取得されます。API記述に特定のパスおよび関連メソッドのレスポンス情報が含まれていない場合は、そのルートに対してデフォルトの標準レスポンス・バックエンドが作成され、HTTPステータス・コードが501になります。

  10. 各デフォルト・ルートを順に確認し、必要な場合は要件を満たすようにその構成を変更して、リクエスト・ポリシー、レスポンス・ポリシーおよびロギング・ポリシーを追加します:

  11. (オプション)「別のルート」を選択して、API記述からデフォルトで作成されるルート以外のルートの詳細を入力します。
  12. 「次」を選択して、新しいAPIデプロイメント用に入力した詳細を確認します。

  13. 「作成」を選択して、新しいAPIデプロイメントを作成します。

    新しいAPIデプロイメントの作成には数分かかる場合があります。作成中のAPIデプロイメントは、「ゲートウェイの詳細」ページに作成中の状態で表示されます。正常に作成されると、新規APIデプロイメントがアクティブの状態で表示されます。

  14. APIデプロイメントがアクティブの状態で表示されるのを数分以上待機していた場合(またはAPIデプロイメント作成操作に失敗した場合):

    1. APIデプロイメントの名前を選択し、「作業リクエスト」を選択してAPIデプロイメント作成操作の概要を表示します。
    2. 「デプロイメントの作成」操作を選択して、操作に関する詳細情報(エラー・メッセージ、ログ・メッセージ、関連付けられたリソースのステータスなど)を表示します。
    3. APIデプロイメントの作成操作が失敗したため、作業リクエスト情報から問題の原因を診断できない場合は、APIゲートウェイのトラブルシューティングを参照してください。
  15. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

CLIの使用

CLIを使用して新しいAPIデプロイメントを作成するには:

  1. CLIを使用するためにクライアント環境を構成します(APIゲートウェイ開発用のCLIを使用するためのクライアント環境の構成)。

  2. コマンド・プロンプトを開き、oci api-gateway deployment createを実行してデプロイメントを作成します:

    oci api-gateway deployment create --compartment-id <compartment-ocid> --display-name <api-name> --gateway-id <gateway-ocid> --path-prefix "/<deployment-path-prefix>" --specification file:///<filename>

    ここでは:

    • <compartment-ocid>は、新しいAPIデプロイメントを作成するコンパートメントのOCIDです。
    • <api-name>は、新しいAPIデプロイメントの名前です。機密情報の入力は避けてください。
    • <gateway-ocid>は、APIをデプロイする既存のゲートウェイのOCIDです。APIゲートウェイのOCIDを確認するには、APIゲートウェイのリストを参照してください。

    • /<deployment-path-prefix>は、APIデプロイメント仕様に含まれているすべてのルートをデプロイするパスです。

      指定するデプロイメント・パス接頭辞は、次の点に注意してください:

      • JSONファイルでは前にスラッシュ(/)を付ける必要があり、単一のスラッシュのみにできます
      • スラッシュは複数使用できますが(隣接していない場合)、スラッシュで終了しないでください
      • 英数字の大文字と小文字を使用できます
      • 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
      • パラメータおよびワイルドカードを含めることはできません

      また、APIデプロイメントのデプロイメント・パス接頭辞として1つのフォワード・スラッシュがある場合、それは特定のAPIゲートウェイで許可される唯一のAPIデプロイメントです。同じAPIゲートウェイに別のAPIデプロイメントがすでに存在する場合、デプロイメント・パス接頭辞として単一のフォワード・スラッシュを使用してAPIデプロイメントを作成することはできません。

    • <filename>は、パス、1つ以上のメソッド、およびバック・エンド定義を含むAPIデプロイメント仕様です。APIデプロイメント仕様の作成を参照してください。

    例:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json

    コマンドへのレスポンスには、次が含まれます:

    • APIデプロイメントのOCID。

    • <gateway-identifier>.apigateway.<region-identifier>.oci.customer-oci.comのフォーマットでドメイン名としてAPIデプロイメントが作成されたホスト名。説明は次のとおりです:

      • <gateway-identifier>は、APIゲートウェイを識別する文字列です。たとえば、lak...sjd(読みやすくするために省略形)と入力します。
      • <region-identifier>は、APIデプロイメントが作成されたリージョンの識別子です。リージョン別の可用性を参照してください。

      たとえば、lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.comです。

      ホスト名は、APIゲートウェイにデプロイされたAPIをコールするときに使用するドメイン名です。

    • ライフサイクルの状態(たとえば、ACTIVE、FAILED)。
    • APIデプロイメントを作成する作業リクエストのID(作業リクエストの詳細は、完了、取消または失敗の後の7日間利用可能です)。

    APIデプロイメントがアクティブになる(またはリクエストが失敗する)までコマンドが制御を返すのを待機する場合は、次のパラメータのいずれかまたは両方を含めます:

    • --wait-for-state ACTIVE
    • --wait-for-state FAILED

    例:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json --wait-for-state ACTIVE

    作業リクエストが正常に作成され、APIデプロイメントがアクティブになるまで、APIデプロイメントを使用できないことに注意してください。

  3. (オプション) APIデプロイメントのステータスを確認するには、次を入力します:

    oci api-gateway deployment get --deployment-id <deployment-ocid>

  4. (オプション) APIデプロイメントを作成している作業リクエストのステータスを確認するには、次を入力します:

    oci api-gateway work-request get --work-request-id <work-request-ocid>

  5. (オプション) APIデプロイメントを作成している作業リクエストのログを表示するには、次を入力します:

    oci api-gateway work-request-log list --work-request-id <work-request-ocid>

  6. (オプション) APIデプロイメントを作成している作業リクエストが失敗し、エラー・ログを確認する場合は、次を入力します:

    oci api-gateway work-request-error --work-request-id <work-request-ocid>

CLIの使用の詳細は、コマンドライン・インタフェース(CLI)を参照してください。CLIコマンドで使用できるフラグおよびオプションの完全なリストについては、CLIのヘルプを参照してください。