APIゲートウェイ・バック・エンドとしてのOCI Functionsでのファンクションの追加
OCI Functionsで定義されたサーバーレス・ファンクションを公開するAPIゲートウェイを使用してAPIデプロイメントを作成する方法をご紹介します。
一般的な要件は、バック・エンドとしてサーバーレス・ファンクションを使用するAPIを構築すること、およびそれらのファンクションに対するフロントエンド・アクセスを提供するAPIゲートウェイを構築することです。
OCI Functionsでは、Dockerイメージとして構築し、指定したDockerレジストリにプッシュするサーバーレス・ファンクションを作成できます。各ファンクションの定義は、OCIファンクション・サーバーにメタデータとして格納されます。ファンクションを初めて起動すると、OCIファンクションは、指定したDockerレジストリからファンクションのDockerイメージを取得し、Dockerコンテナとして実行してファンクションを実行します。同じファンクションに対する後続のリクエストがある場合、OCIファンクションはそれらのリクエストを同じ実行中のコンテナに送ります。アイドル状態の期間の後、Dockerコンテナは停止されます。
APIゲートウェイ・サービスを使用してAPIゲートウェイを作成すると、OCIファンクションで定義されたサーバーレス・ファンクションを呼び出すAPIデプロイメントを作成できます。
OCI Functionsのサーバーレス・ファンクションをAPIのバック・エンドとして使用する前に:
- APIデプロイメント仕様で参照されるサーバーレス・ファンクションは、すでに作成されてOCIファンクションにデプロイされている必要があります。ファンクションは、(パブリックAPIゲートウェイの場合は)インターネット・ゲートウェイを介して、または(プライベートAPIゲートウェイの場合は)サービス・ゲートウェイを介して、APIゲートウェイに指定されたVCNからルーティング可能である必要があります。ファンクションの作成およびデプロイを参照してください。関連する開発者チュートリアルについては、ファンクション: APIゲートウェイを使用したファンクションのコールを参照してください。
次に対してOCIファンクションで定義されたサーバーレス・ファンクションへのアクセス権を付与する適切なポリシーが、すでに存在している必要があります:
- ユーザー・アカウントが属するグループ(ファンクションへのAPIゲートウェイ・ユーザー・アクセスを提供するポリシーの作成を参照)
- APIゲートウェイ(APIゲートウェイにファンクションへのアクセス権を付与するポリシーの作成を参照)
サーバーレス・ファンクションのバック・エンドをAPIデプロイメント仕様に追加するには、次を実行します:
- コンソールの使用
- JSONファイルの編集
APIゲートウェイのバック・エンドとして使用するためのOCI関数でのサーバーレス・ファンクションの作成およびデプロイ
APIゲートウェイから起動できるOCIファンクションのサーバーレス・ファンクションを作成するには、OCIファンクション・ドキュメントの手順に従って次を実行します:
- 「ファンクションの準備」の説明に従って、OCIファンクションを使用するための前提条件ステップを完了していることを確認します。
- ファンクションの作成およびデプロイの説明に従って、APIゲートウェイにアクセス権が付与されたコンパートメントでファンクションを作成およびデプロイします。
コンソールを使用したAPIデプロイメント仕様へのサーバーレス・ファンクション・バック・エンドの追加
コンソールを使用してOCIファンクション・バック・エンドをAPIデプロイメント仕様に追加するには:
-
コンソールを使用してAPIデプロイメントを作成し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイの更新を参照してください。
-
「認証」ページで、認証オプションを指定します。
認証オプションの詳細は、APIデプロイメントへの認証と認可の追加を参照してください。
-
「ルート」ページで、新しいルートを作成し、次を指定します:
-
パス: リストされたメソッドを使用したバックエンド・サービスへのAPIコールのパス。指定するルート・パスで次の点に注意してください:
- デプロイメント・パス接頭辞に対して相対的です(APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照)
- 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
- スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
- 英数字の大文字と小文字を使用できます
- 特殊文字
$ - _ . + ! * ' ( ) , % ; : @ & =
を使用できます - パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
- メソッド: バックエンド・サービスが受け入れた1つ以上のメソッド。たとえば、
GET, PUT
です。 -
単一のバックエンドの追加または複数のバックエンドの追加: すべてのリクエストを同じバックエンドにルーティングするか、入力したコンテキスト変数およびルールに従ってリクエストを異なるバックエンドにルーティングするか。
これらの手順では、単一のバックエンドを使用することを想定しているため、「単一のバックエンドの追加」を選択します。または、異なるバック・エンドを使用する場合は、「複数のバックエンドの追加」を選択し、コンソールを使用したAPIデプロイメント仕様への動的バック・エンド選択の追加の手順に従います。
- バックエンド・タイプ:バックエンド・サービスのタイプ(
Oracle Functions
)。 - <compartment-name>のアプリケーション:ファンクションを含むOCIファンクションのアプリケーションの名前。別のコンパートメントからアプリケーションを選択できます。
- 関数名: OCI関数の名前。
この例のルートでは、OCI Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています。
フィールド: 入力: パス: /hello
メソッド: GET
バックエンド・タイプ: Oracle Functions
<compartment-name>のアプリケーション: acmeapp
関数名: acme-func
-
- (オプション)「別のルート」を選択して、追加ルートの詳細を入力します。
- 「次」を選択して、APIデプロイメント用に入力した詳細を確認します。
- APIデプロイメントを作成または更新するには、「作成」または「変更の保存」を選択します。
-
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。
サーバーレス・ファンクションがパラメータを受け入れる場合は、APIへのコールにそれらを含めます。例:
curl -k -X GET https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/marketing/hello/ -d "name=john"
JSONファイルの編集によるAPIデプロイメント仕様へのサーバーレス・ファンクション・バック・エンドの追加
OCIファンクション・バック・エンドをJSONファイルのAPIデプロイメント仕様に追加するには:
-
任意のJSONエディタを使用し、JSONファイル内に次のフォーマットでAPIデプロイメント仕様を作成します:
{ "requestPolicies": {}, "routes": [ { "path": "<api-route-path>", "methods": ["<method-list>"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "<identifier>" }, "requestPolicies": {} } ] }
ここでは:
"requestPolicies"
は、APIデプロイメントの動作を制御するオプションのポリシーを指定します。APIデプロイメント仕様のすべてのルートにポリシーを適用する場合は、routes
セクションの外にポリシーを配置します。特定のルートのみにポリシーを適用する場合は、ポリシーをroutes
セクション内に配置します。APIデプロイメント仕様へのリクエスト・ポリシーとレスポンス・ポリシーの追加を参照してください。-
<api-route-path>
には、バックエンド・サービスに対してリストされているメソッドを使用して、APIコールのパスを指定します。指定するルート・パスで次の点に注意してください:- デプロイメント・パス接頭辞に対して相対的です(APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照)
- 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
- スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
- 英数字の大文字と小文字を使用できます
- 特殊文字
$ - _ . + ! * ' ( ) , % ; : @ & =
を使用できます - パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
<method-list>
は、バックエンド・サービスによって受け入れられる1つ以上のメソッドをカンマで区切って指定します。たとえば、"GET, PUT"
です。<identifier>
は、バックエンド・サービスとして使用するファンクションのOCIDを指定します。たとえば、"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
です。
たとえば、次の基本的なAPIデプロイメント仕様では、OCI Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
- APIデプロイメント仕様を含むJSONファイルを保存します。
-
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- JSONファイルをコンソールで「既存のAPIのアップロード」オプションで指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照してください。
-
(オプション) APIがデプロイされていること、およびAPIをコールしてOCIファンクションのサーバーレス・ファンクションが正常に起動できることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。
サーバーレス・ファンクションがパラメータを受け入れる場合は、APIへのコールにそれらを含めます。例:
curl -k -X GET https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/marketing/hello/ -d "name=john"