関数の処理

関数は、 HTTP リクエストによって呼び出されるタスクを実行する、ステートレスなコードスニペットである。 IBM Code Engine 関数を使えば、スケーラブルでサーバーレスな方法でビジネスロジックを実行できる。 IBM Code Engine 機能は、低レイテンシーと迅速なスケールアウトシナリオをサポートするために最適化されたランタイム環境を提供する。関数コードは、特定の Node.js または Python バージョンを含むマネージド・ランタイムで書くことができます。

コード・バンドルは、機能コードを表すファイルの集合です。このコード・バンドルは、ランタイム・コンテナーに注入されます。コード・バンドルは Code Engine によって作成され、コンテナー・レジストリーに保管されるか、関数とともにインラインで保管されます。コード・バンドルは、Open Container Initiative (OCI) 標準コンテナー・イメージではありません。

開始前に

Code Engine コンソールを使用したい場合は、 Code Engine overview にアクセスしてください。
CLI を使用する場合は、Code Engine の CLI 環境をセットアップします。
コードを Code Engine ファンクション・コンポーネントとして実行させるためのアプローチを計画し、選択する。

作成する Code Engine ワークロードのタイプがわからない場合があります。 Code Engine の計画を参照してください。

機能の制限

イベント・プロデューサーのサブスクライブはサポートされていません。
Terraform はサポートされていません。

自分のコードを Code Engine ファンクション・コンポーネントとして実行させるには？

コードがソースとしてローカルファイルや Git リポジトリに存在する場合でも、コードがパブリックまたはプライベートレジストリにある既存のコードバンドルである場合でも、 Code Engine は、コードを関数として実行する合理的な方法を提供します。

Git リポジトリにあるソースコードから始める場合、ソースの場所を指定すると、 Code Engine がソースからコードバンドルをビルドし、1回の操作で関数を作成します。このシナリオでは、 Code Engine があなたのコードを IBM Cloud® Container Registry にアップロードします。詳しくは、リポジトリー・ソース・コードからの関数の作成を参照してください。
ローカル・ワークステーションのソース・コードから始める場合、ソースの場所を指定すると、 Code Engine、CLIコマンド 1つでソースからイメージをビルドし、関数を作成します。このシナリオでは、 Code Engine があなたのコードを IBM Cloud® Container Registry にアップロードします。詳しくは、 CLI を使用したローカル・ソース・コードからの関数の作成を参照してください。
ソース・コードから開始する場合は、ソース・コードをインラインで実行することもできます。このシナリオでは、関数の作成時にソース・コードを貼り付けます。詳しくは、インライン・コードを使用した関数の作成を参照してください。

関数を作成し、実行した後は、関数の作成方法や更新方法に関係なく、前述のいずれかの方法で関数を更新することもできます。

関数を呼び出すとどうなりますか?

関数が呼び出される (開始される) と、対応する関数インスタンスが、構成されたランタイム・コンテナーおよびリソース・パラメーターを使用して初期化されます。最初の初期設定のプロセスは、 コールド・スタートと呼ばれます。

コールド・スタートの待ち時間を削減するために、 Code Engine は、特定の CPU とメモリーの構成で特定のランタイムを事前にウォーミングすることによって、呼び出しを最適化します。ファンクション用のプリウォームドコンビネーションには、 Node.js と Python のランタイムと、ファンクション用のデフォルトのCPUとメモリの組み合わせ（ 0.25 vCPU x メモリ1GB）がある。さらに、システムは、既に初期化されている関数インスタンスの再使用を改善するように設計されています。したがって、関数インスタンスは、呼び出しの完了後に存続し、同じインスタンスを再利用し、最後の呼び出しが完了したときにインスタンスの状態を再利用することにより、後続の呼び出しを可能にします。関数インスタンスの再利用は保証されません。

関数インスタンスの存続期間を長くすることはできますか?

Code Engineを使用すると、ワークロードに基づいて関数が自動的にスケールアップ/スケールダウンします。デフォルトの CPU とメモリーの組み合わせを使用して関数を作成すると、関数は「事前ウォーム」コンテナーに注入されます。このコンテナーは使用するために最適化されています。デフォルトの組み合わせ以外の CPU とメモリーの組み合わせを使用して関数を作成すると、関数は新しいコンテナーに注入されます。デフォルトでは、このコンテナーは、機能が完了してから少しの間だけ存続します。詳しくは、関数でサポートされる CPU とメモリーの組み合わせを参照してください。

CLI の --scale-down-delay オプション、またはコンソールの 「スケールダウン遅延」 オプションを使用して、コンテナーが存続している時間を変更できます。コンテナーを活動状態にしておくと、機能の後続の実行のコールド・スタート時間が短縮されますが、カスタム機能コンテナーが存在する時間も請求されることに注意してください。

要求と応答

関数は HTTP プロトコルで呼び出される。関数を呼び出す際に、カスタムリクエストパラメータ、カスタムリクエストボディ、カスタムリクエストヘッダ、 HTTP メソッドを指定することができます。要求パラメーターは、入力パラメーターとして機能コードで使用可能になります。関数コードは、関数エンドポイントから呼び出し元に返される応答本体、応答ヘッダー、および応答コードを設定できます。

例 1: 関数から HTML 応答を生成する

以下の例は、関数から HTML 応答を生成する方法を示しています。

  function main(params) {
      var msg = 'You did not tell me who you are.';
      if (params.name) {
          msg = `Hello, ${params.name}!`
       } else {
          msg = `Hello, FaaS on CodeEngine!`
      }
      return {
          headers: { 'Content-Type': 'text/html; charset=utf-8' },
          body: `<html><body><h3>${msg}</h3></body></html>`
       }
  }

  module.exports.main = main;

例 2: 応答コードと応答ヘッダーの設定

関数は、特定の応答コードおよびヘッダー・フラグを設定することができます。次の例は、レスポンスコードとレスポンスヘッダを設定して、別の URL にリダイレクトを追加する方法を示している。

function main(params) {
    return {
        headers: { location: 'https://cloud.ibm.com/docs/codeengine' },
        statusCode: 302
    }
}

例 3: 関数からプレーン・テキスト応答を生成する

以下の例は、関数からプレーン・テキスト応答を生成する方法を示しています。

function main(params) {
    var msg = 'You did not tell me who you are.';
    if (params.name !== "") {
        msg = `Hello, ${params.name}!`
    }
    return {
        headers: { 'Content-Type': 'text/plain;charset=utf-8' },
        body: `${msg}`
    }
}

エラー処理とデバッグ

関数呼び出しは、システム・エラーまたはアプリケーション・エラーを返す可能性があります。例えば、システム・エラーは機能コードが正常に実行されなかったことを示し、アプリケーション・エラーは機能コード自体の問題を示します。

システム・エラーが発生すると、以下のコードに似た HTTP 応答コードが返される。

HTTP 応答コード
コード	説明
409	機能に必要なリソースが満たされませんでした。
413	要求ペイロードが定義された最大値を超えています。
414	呼び出し URI が長すぎます。
416	関数は、定義された最大値を超える応答を生成しました。
422	ファンクションコードは無効であり、処理できません。詳細は、プラットフォームのログを参照してください。
424	ファンクションコードが実行できなかった。後でもう一度試してください。
429	リソース割り当て量を超過したため、機能をスケジュールできませんでした。
431	要求ヘッダーが、定義された最大値を超えています。
500	内部サーバー・エラー
502	不正なゲートウェイです。
503	この機能は現在使用できません。
507	関数をロードするためのストレージが不足しています。

Code Engine が関数コードを実行できる場合は、以下のいずれかの状況コードで呼び出しに応答します。

状況コード
コード	説明
200	関数呼び出しが受け入れられました。関数は遅延して実行されます。
202	関数呼び出しが受け入れられました。関数は非同期的に実行されます。
299	関数は、指定されたランタイム制限または最大ランタイム制限を超えたため、中止されました。

関数の開発者として、先に挙げたものであっても、任意の HTTP ステータスコードを生成することができる。したがって、応答ヘッダーは、状況コードが機能コードによって生成されたことを示します。

Code Engine 関数は、関数呼び出し応答に以下の応答ヘッダーを追加します。

状況コード
コード	説明
`x-faas-actionstatus`	ファンクション・プログラム・ロジックによって設定される HTTP ステータス・コード。
`x-faas-activation-id`	関数呼び出しを識別するための固有 ID。
`x-faas-result`	ランタイム・コンテナーによって返される `success` メッセージまたは短いエラー・メッセージ。
`x-faas-errormessage`	詳細を示す長いエラー・メッセージ。
`x-faas-prewarmed`	呼び出しがコールド呼び出しであったかどうか、または関数が既存の (事前ウォーム・コンテナー) で実行されたかどうかを示すメッセージ。可能な値は `false` または `true` です。

関数データの入出力特性

Code Engineで関数を実行するには、以下の特性を持つランタイム・コントラクトをコードに実装する必要があります。

ウェブページに埋め込まれ、 Code Engine Eventingソース、ウェブブラウザ、またはその他の HTTPS が可能なクライアントから呼び出すことができるように、パブリックウェブアプリケーションのエンドポイントから呼び出し可能でなければならない。
エントリー・ポイントとして main プロシージャーを実装する必要があります。 main プロシージャーは、JSON 形式のデータ構造の形式で入力パラメーターを受け取ることができ、JSON 形式のデータ構造の形式でも出力パラメーターを返すことができます。
関数が指定されたパスに基づいて異なるフレーバーを実装できるように、オプションのサブパスを受け取ることができます。関数の main プロシージャーは、 __ce_path 入力パラメーターとしてパスを受け取ります。
実行時に関数を構成するために使用できるオプションの照会パラメーターを受け取ることができます。関数の main プロシージャーは、JSON 形式の入力データ構造内でキーと値のペアとしてパラメーターを受け取ります。
クライアント・コードが受け入れられるエンコードを指定できるように、要求ヘッダーを受け取ることができます。
オプションのコンテンツ・タイプ要求ヘッダーを受け取ることができます。
関数が実行時に処理するオプションの要求ペイロード (本体) を受け取ることができます。選択された要求コンテンツ・タイプに応じて、データ・ペイロードは、Base64 エンコード形式または JSON 入力データ構造の一部として関数のメイン・エントリー・ポイントに渡されます。 application/x-www-form-urlencoded 入力のキーと値のペアに含まれる特殊文字は、 percent-encoded 値です。
任意の HTTP ステータスコードを定義することができる（オプション）。
任意の応答ヘッダー (リダイレクト・ロケーション、応答エンコード、Cookie 値など) を設定できます。
選択されたバイナリー・エンコードまたは非バイナリー・エンコードを使用して、任意の応答本体を返すことができます。例えば、 application/octet-stream、 application/json、 text/*、 image/*、または audio/* などです。 content-type 応答ヘッダーが設定されていない場合、デフォルトで text/plain に設定されます。
次の要求コンテンツ・タイプをサポートします: application/x-www-form-urlencoded (デフォルト)、 text/plain、 application/json、 application/octet-stream、 image/*、 audio/*
multipart/form-data 要求ヘッダーをサポートしません。

Code Engine 関数の表示オプション

Code Engine では、リクエストを受け取るために利用可能なエンドポイント、またはシステム・ドメイン・マッピングを定義することによって、機能の適切な可視性レベルを決定することができます。

すべてのファンクションは、同じ Code Engine プロジェクト内のすべてのコンポーネントから見える内部システムドメインマッピングを持ちますが、プロジェクトの外部からは見えません。内部システム・ドメイン・マッピングに加えて、 パブリック ・インターネットまたは IBM Cloud プライベート ・ネットワークのいずれかに対して機能を可視にすることを選択します。

公開または非公開の可視性のために、関数は HTTPS エンドポイントで公開される。使用されるTLS証明書の詳細については、 Code Engine プロジェクトのTLS証明書を参照してください。

以下の可視性レベルで関数をデプロイできます。

機能の可視性
設定	説明
内部(プロジェクト)	この設定の関数は、同じ Code Engine プロジェクト内のコンポーネントから要求を受け取ることができます。内部（プロジェクト）エンドポイントを設定するということは、あなたの機能が公共のインターネットからアクセスできないことを意味し、ネットワークアクセスは、同じ Code Engine プロジェクト内で実行されている他の Code Engine コンポーネントからのみ可能です。このエンドポイントは常に有効です。重要：関数は、内部ルートを使用して別のジョブまたはアプリケーションを呼び出すことはできません。
パブリック	この設定をした関数は、インターネットとあなたの Code Engine ・プロジェクトに公開されます。パブリック・エンドポイントを設定するということは、あなたの関数が一般のインターネットや、 Code Engine プロジェクト内のコンポーネントからのリクエストを受け取ることができることを意味します。この設定がデフォルトです。
プライベート	この設定を持つ関数は、 IBM Cloud プライベート・ネットワークと Code Engine プロジェクトに公開されます。プライベート・エンドポイントを設定するということは、あなたの機能がパブリック・インターネットからアクセスできないことを意味し、ネットワーク・アクセスは、同じプロジェクト内で実行されているバーチャル・プライベート・エンドポイント（VPE）または Code Engine コンポーネントを使用することによって、他の IBM Cloud サービスからのみ可能となります。

関数の可視性のエンドポイント設定は、関数を作成、デプロイ、または更新するときに、コンソールから、または CLI を使用して設定できます。

内部エンドポイントを使用した関数のデプロイ

内部 (プロジェクト) エンドポイントを使用してデプロイする関数のエンドポイント可視性を設定できます。内部 (プロジェクト) エンドポイントを設定すると、パブリック・インターネットから機能にアクセスできなくなり、同じ Code Engine プロジェクト内で実行されている他の Code Engine コンポーネントからのみネットワーク・アクセスが可能になります。このエンドポイントは常に有効です。関数は依然として共有コンポーネントを通じてアクセス可能であるため、安全性を確保する必要がある。

例えば、ソリューションがプロジェクト内の複数の機能で構成されている場合、そのうちの1つの機能だけがインターネットから見えるようにソリューションを設定し、それが受信トラフィックを処理するようにすることができる。この一般向け機能は、インターネットから見える必要がないように、ソリューション内の他の機能に作業を委任することができる。

CLI で、 function create または function update コマンドの --visibility=project オプションを使用して、関数がプロジェクト・エンドポイントとともにデプロイされるように、関数のエンドポイント可視性を設定します。 function get コマンドを使用して、エンドポイント定義を反映する機能の使用可能な URL を取得できます。

コンソールから、関数の作成時に 「エンドポイント」 設定を使用して、関数のエンドポイントの可視性を設定します。関数をデプロイした後、「関数」ページの 「ドメイン・マッピング」 タブで、これらのシステム・ドメイン・マッピング設定を表示および変更できます。

この設定の関数は、同じ Code Engine プロジェクト内のコンポーネントから要求を受け取ることができます。ただし、関数は内部ルートを使用して別のジョブまたはアプリケーションを呼び出すことはできません。

パブリックエンドポイントを使った関数のデプロイ

関数をデプロイすると、デフォルトで、関数はパブリック・インターネットから、または同じ Code Engine プロジェクト内のコンポーネントから要求を受け取ることができます。この場合、この関数はパブリック・エンドポイントで配備される。

プライベートエンドポイントを使った関数のデプロイ

プライベート・エンドポイントを使用してデプロイする関数のエンドポイント可視性を設定できます。機能にプライベート・エンドポイントを設定すると、パブリック・インターネットからはアクセスできなくなり、ネットワーク・アクセスは、同じプロジェクト（クラスタ・ローカル）で実行されている仮想プライベート・エンドポイント（VPE）または Code Engine コンポーネントの他の IBM Cloud サービスからのみ可能になります。

例えば、ソリューションが独自の仮想プライベート・エンドポイント内の IBM Cloud Kubernetes Service Kubernetes クラスター上で実行されているコンポーネントで構成されており、 IBM Cloud プライベート・ネットワークから Code Engine 関数にアクセスしたい場合、関数の可視性をプライベートに設定することができます。ファンクションの可視性がプライベートに設定されている場合、そのファンクションは公共のインターネットからはアクセスできません。この関数は、プロジェクト内の他の関数からもアクセスできる。

プライベート・エンドポイントを使用して関数を作成して、関数が IBM Cloud プライベート・ネットワークを介してのみ公開され、外部インターネットに公開されないようにすることができます。この機能は、内部ネットワークから共有コンポーネントを通じて到達可能であり、機能のエンドポイントを保護する必要がある。

CLI で、 function create または function update コマンドの --visibility=private オプションを使用して、関数がプライベート・エンドポイントでデプロイされるように、関数のエンドポイント可視性を設定します。 function get コマンドを使用して、エンドポイント定義を反映する機能の使用可能な URL を取得できます。

プライベート・ネットワークを介した接続について詳しくは、Code Engineでの仮想プライベート・エンドポイントの使用を参照してください。

関数を作成するためのオプション

関数を作成する際に指定できるオプションについて説明します。なお、コンソールと CLI でオプションが異なる場合があります。

メモリーと CPU

関数をデプロイする際に、その関数が消費できるメモリとCPUの量を指定することができます。これらの量は、あなたの機能が計算集約型か、メモリ集約型か、あるいはバランス型かによって異なる。

デフォルトでは、ファンクションには 4 G のメモリと 1.0 vCPU が割り当てられています。サポートされる他のメモリーと CPU の組み合わせについて詳しくは、関数でサポートされるメモリーと CPU の組み合わせを参照してください。

環境変数を使った関数の作成と実行

環境変数は、実行時に関数で使用できるキーと値のペアとして定義・設定することができます。

環境変数は、関数を作成するとき、またはCLIで既存の関数を更新するときに定義できます。

環境変数を定義する方法について詳しくは、環境変数の扱いを参照してください。

Code Engine は、特定の環境変数を自動的に関数に注入する。自動注入される環境変数について詳しくは、環境変数の自動注入を参照してください。

シークレットとコンフィグマップを使用する場合の関数の作成と実行

Code Engine では、シークレットとコンフィグマップは、環境変数を使用することで、あなたの関数で消費することができます。

シークレットと構成マップは、どちらもキーと値のペアです。環境変数にマップされると、環境変数の名前がマップの各項目の「キー」に対応し、環境変数の値がそのキーの「値」になるように NAME=VALUE の関係が設定されます。

あなたの関数は、環境変数を使用してコンフィグマップ（またはシークレット）を完全に参照したり、コンフィグマップ（またはシークレット）内の個々のキーを参照したりすることができます。

詳しくは、環境変数を使用したシークレットの参照および環境変数を使用した構成マップの参照を参照してください。

機能割り当て量に関する考慮事項

アプリケーション、関数、およびバッチ・ジョブを処理する場合、これらのリソースは Code Engine プロジェクトのコンテキスト内で実行されます。リソース割り当て量はプロジェクトごとに定義され、制限はアプリケーション、機能、およびバッチ・ジョブに適用されます。

Code Engine の制限について詳しくは、Code Engine の制限と割り当て量を参照してください。

次のステップ

Code Engine 機能を操作するための主要な概念を理解したので、機能を作成して操作する準備はできていますか? 以下のトピックを参照してください。

ファンクションの詳細については、以下のトピックを参照してください。