Atlas Function

Atlas Function は、アプリの動作を定義するためにユーザーが記述するサーバーサイドの JavaScript コードです。アプリの関数をクライアントから直接呼び出すことも、関数を自動的に統合して呼び出すサービスを定義することもできます。

関数は、他の関数を呼び出して、MongoDB Atlas クラスター内のデータを操作するための組み込みクライアントを含めることができます。関数はまた、便利なグローバルユーティリティを含み、一般的な Node.js 組み込みモジュールをサポートし、npm レジストリから外部パッケージをインポートして使用することもできます。

あいさつを返す基本的な関数

exports = function(name) {
  return `Hello, ${name ?? "stranger"}!`
}

関数はサーバーレス

アプリは関数が呼び出されると、コードを評価し結果を返す管理型アプリサーバーにリクエストをルーティングします。このモデルでは関数はサーバーレスになるため、ユーザーがコードを実行するサーバーを配置・管理する必要はありません。代わりに、ユーザーは関数のソースコードを記述し、アプリが実行環境を取り扱います。

関数にはコンテキストが付属

関数は、その実行環境を反映したコンテキストの枠内で実行されます。コンテキストの例として、関数を呼び出したユーザー、関数の呼び出し方法、呼び出し時のアプリの状態が挙げられます。コンテキストを使用することで、ユーザー固有のコードの実行やアプリの他の部分との連携が可能になります。

関数コンテキストとの連携方法の詳細については、「コンテキスト」を参照してください。

関数は外部サービスを呼び出すことができます

送信HTTPリクエストを実行する関数（例、http 外部パッケージを使用することで）を作成して、関数内で使用する組織外のデータにアクセスできます。

注意

アウトバウンド IP アドレス

外部サービスには、特定のIPアドレスからの呼び出すへのアクセスを制限するファイアウォールがある場合があります。その場合は、そのサービスに承認されたIPリストを設定する必要があります。詳細については、関数セキュリティのアウトバウンドIPアクセスを参照してください。

関数を使用可能なケース

関数はユーザーが定義した任意の JavaScript コードを実行できるため、ほぼすべての目的で使用できます。レイテンシが低く、実行時間が短いタスク（データの移動、変換、検証など）は関数の一般的なユースケースです。また、外部サービスに接続したり、クライアントアプリケーションから詳しい実装情報を抽象化したりする目的でも関数を使用できます。

triggerは、特定のイベントを処理するために関数を自動的に呼び出します。例、データベースtriggerで変更イベントが観察されるたびに、変更イベントを引数として関連する関数が呼び出されます。 trigger 関数を利用すると、変更イベントの情報にアクセスして、適宜、対応できます。

注意

データベーストリガーと予定されたトリガーは常にシステムユーザーのコンテキストで実行されます。

関数の記述方法

関数のコードは基本的に名前付きのJavaScriptソースファイルであるため、1 つの関数ファイルに複数のJavaScript関数を定義できます。このファイルは 1 つのJavaScript関数をエクスポートする必要があり、呼び出しを受信したときのエントリポイントとして機能します。関数を名前で呼び出すと、実際には関数のソースファイル内のexportsに割り当てられたJavaScript関数が呼び出されます。

以下は、name 引数を受け取り、ログメッセージを追加し、指定された名前にあいさつを返す単純な関数の例です。

exports = function Hello(name) {
   console.log(`Said hello to ${name}`);
   return `Hello, ${name}!`;
};

最新の JavaScript 構文とインポートパッケージを使用すると、より複雑な関数を定義できます。

// You can use ES6 arrow functions
const uppercase = (str) => {
   return str.toUpperCase();
};
// You can use async functions and await Promises
exports = async function GetWeather() {
// You can get information about the user called the function
const city = context.user.custom_data.city;
// You can import Node.js built-ins and npm packages
const { URL } = require("url");
const weatherUrl = new URL("https://example.com");
weatherUrl.pathname = "/weather";
weatherUrl.search = `?location="${city}"`;
// You can send HTTPS requests to external services
const weatherResponse = await context.http.get({
   url: url.toString(),
   headers: {
      Accept: ["application/json"],
   },
});
const { current, forecasts } = JSON.parse(weatherResponse.body.text());
return [
   `Right now ${uppercase(city)} is ${current.temperature}°F and ${current.weather}.`,
   `Here's the forecast for the next 7 days:`,
   forecasts
      .map((f) => `${f.day}: ${f.temperature}°F and ${f.weather}`)
      .join("\n  "),
].join("\n");
};

Right now NEW YORK CITY is 72°F and sunny.
Here's the forecast for the next 7 days:
  Tuesday: 71°F and sunny
  Wednesday: 72°F and sunny
  Thursday: 73°F and partly cloudy
  Friday: 71°F and rainy
  Saturday: 77°F and sunny
  Sunday: 76°F and sunny
  Monday: 74°F and sunny

関数は返された値を拡張 JSON に自動的に直列化します。これはタイプ情報を保持するには便利ですが、アプリケーションにとって例外的な処理である場合があります。

たとえば、次の関数から返されるオブジェクトの値は、構造化された EJSON 値に変換されます。

exports = function() {
  return {
    pi: 3.14159,
    today: new Date(),
  }
}

{
  "pi": {
    "$numberDouble": "3.14159"
  },
  "today": {
    "$date": {
      "$numberLong": "1652297239913"
    }
  }
}

値を標準的な JSON として返すために、値に対して JSON.stringify() を呼び出すと、次のように文字列化された結果が返されます。

exports = function() {
  return JSON.stringify({
    pi: 3.14159,
    today: new Date(),
  })
}

"{\"pi\":3.14159,\"today\":\"2022-05-11T19:27:32.207Z\"}"

関数の定義

Atlas UIを使用するか、 App Services CLIまたはGithub配置を使用して関数の構成とソースコードをインポートすることで、関数をアプリケーションで作成、管理できます。

Atlas UIからサーバー側の関数を新規定義できます。

Atlas で、プロジェクトの Triggers ページに移動します。

まだ表示されていない場合は、プロジェクトを含む組織をナビゲーションバーの Organizations メニューで選択します。
まだ表示されていない場合は、ナビゲーションバーの Projects メニューからプロジェクトを選択します。
サイドバーで、 Streaming Data見出しの下のTriggersをクリックします。

Triggersページが表示されます。

Functions ページに移動します

Linked App Service: Triggersリンクをクリックします。
サイドバーで、 Build見出しの下のFunctionsをクリックします。
[ Create a Functionをクリックします。 Settingsタブにはデフォルトでが表示されます。

新規関数の命名

Nameフィールドに関数の名前を入力します。この名前は、アプリケーション内の他のすべての関数と一意である必要があります。

Tip

ネストされたフォルダーの中に関数を定義することができます。関数名はスラッシュで区切られたパスになっており、utils/add という名前の関数はアプリの構成ファイルの functions/utils/add.js にマップされます。

ユーザー認証の設定

Atlas の関数は常に特定のアプリケーションユーザー配下で、またはルールをバイパスするシステムユーザーとして実行されます。関数の実行ユーザーを構成するには、Atlas が使用する認証のタイプを指定します。

注意

データベーストリガーとスケジュールされたトリガーの関数は常にシステムユーザーのコンテキストで実行されます。

認証タイプ	説明
アプリケーション認証（非推奨）	非推奨。このタイプの認証では、クライアントアプリケーションが関数を呼び出す時にログインした既存のアプリケーションユーザー配下で関数を実行するように設定されます。関数が別の関数から呼び出された場合は、その関数から実行ユーザーを継承します。
システム	このタイプの認証では、 MongoDBのCRUDおよび集計 API へのフルアクセス権を持ち、ルール、ロール、または権限の影響を受けないシステムユーザーとして関数を実行するように構成されます。
ユーザーID （非推奨）	非推奨。このタイプの認証では、常に特定のアプリケーションユーザーとして関数が実行されるように設定されます。
スクリプト	このタイプの認証では、定義したカスタム関数の結果に基づいて決定された特定のアプリケーションユーザーとして関数を実行するように構成されます。関数は特定のユーザーの`id` string を返す必要があります。または、 `{ "runAsSystem": true }`を返すことでシステムユーザーを指定することもできます。

関数ログの設定

デフォルトでは、Atlas では関数を実行するたびに、関数が受け取った引数がログエントリに含まれます。

Atlas が引数をログに記録しないようにするには、 Log Function Argumentsを無効にします。

承認式の指定

You can dynamically authorize requests based on the contents of each request by defining a Can Evaluate expression. Atlas evaluates the expression whenever the Function is called. If you do not specify an expression, Atlas automatically authorizes all authenticated incoming requests.

The expression can expand standard expression variables, including the %%request and %%user expansions.

クリックして拡大します

関数のプライバシーレベルの設定

デフォルトで、クライアントアプリケーションから関数を呼び出すことも、同じアプリケーション内の他の関数を呼び出すこともできます。Private を true に設定すると、クライアントアプリケーションからの関数の参照や呼び出しを防ぐことができます。

プライベート関数は引き続き、式やその他の関数（受信 Web フックや受信トリガーを含む）から呼び出すことができます。

クリックして拡大します

関数コードの書込み

新規関数を作成して構成が終わったら、その関数を呼び出すときに実行されるJavaScriptコードを記述できます。

関数エディターを使用して、Atlas UIから直接コードを書くことができます。

Create Functionページから、 Function Editorタブをクリックします。
関数に javascript コードを追加します。少なくとも、次の例のように、コードは exports に関数を割り当てる必要があります。
exports = function() { return "Hello, world!"; };
注意
async/await、分割代入、およびテンプレートリテラルなど、ほとんどの最新のJavaScript（ES6 以降）機能を関数で使用できます。

関数の保存

Save をクリックします。関数を保存したら、すぐに使用できます。

MongoDB Atlas ユーザーの認証

MongoDB Atlas Administration APIキーを使用して、App Services CLI にログします。

appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>"

アプリの最新の構成ファイルを取得する

次のコマンドを実行して、構成ファイルのローカルコピーを取得します。

appservices pull --remote=<App ID>

デフォルトでは、コマンドは現在の作業ディレクトリにファイルをプルします。任意の--localフラグを使用してディレクトリパスを指定できます。

関数のソースコードの記述

Atlas 関数は、個々のファイルからエクスポートする標準の JavaScript（ES6 以降）関数を実行します。

functionsディレクトリまたはサブディレクトリに.jsファイルを作成します。
ファイル名は関数名と一致する必要があります。サブディレクトリパスを示すには、ファイル名の中にスラッシュを使う。

touch functions/<FunctionName>.js

Tip

functionsディレクトリ内のネストされたフォルダー内で関数を定義できます。関数名の中にスラッシュを使うことで、その関数のディレクトリパスを示します。例、utils/add という名前の関数はfunctions/utils/add.js にマップされます。

作成されたファイルに関数ソースコードを記述します。

例、次の関数hello.jsは、指定された名前に対してあいさつを返します。

functions/hello.js

exports = async function hello(...args) {
  // Write your function logic here! You can...
  // Import dependencies
  const assert = require("assert")
  assert(typeof args[0] === "string")
  // Use ES6+ syntax
  const sayHello = (name = "world") => {
    console.log(`Hello, ${name}.`)
  }
  // Return values back to clients or other functions
  return sayHello(args[0])
}

注意

async/await、分割代入、およびテンプレートリテラルなど、ほとんどの最新のJavaScript（ES6 以降）機能を関数で使用できます。

機能の設定

In the functions directory of your local application, open the config.json file and add a configuration object for your new Function to the array.

オブジェクトは次の形式である必要があります。

{
  "name": "<Function Name>",
  "private": <Boolean>,
  "can_evaluate": { <JSON Expression> },
  "disable_arg_logs": <Boolean>,
  "run_as_system": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

ユーザー認証を設定します。
Atlas の関数は常に特定のアプリケーションユーザー配下で、またはルールをバイパスするシステムユーザーとして実行されます。関数の実行ユーザーを構成するには、Atlas が使用する認証のタイプを指定します。
注意
データベーストリガーとスケジュールされたトリガーの関数は常にシステムユーザーのコンテキストで実行されます。
- システムユーザー: システムシステムユーザーとして関数を実行するには、次の構成を使用します。
  システムユーザー構成
  { "run_as_system": true, "run_as_user_id": "", "run_as_user_id_script_source": "" }
- スクリプト: 別の関数から返されたユーザーとして関数を実行するには、次の構成を使用します。
  スクリプト構成
  { "run_as_system": false, "run_as_user_id": "", "run_as_user_id_script_source": "<Function Source Code>" }
- ユーザー（非推奨） : 個別のユーザーとして関数を実行するには、次の構成を使用します。
  ユーザーIDの構成（非推奨）
  { "run_as_system": false, "run_as_user_id": "<App Services User Id>", "run_as_user_id_script_source": "" }
関数ログを設定する
関数を実行するたびに、関数が受け取った引数をログエントリに含めるには、 disable_arg_logsをfalseに設定します。
認可式を指定します。
You can dynamically authorize requests based on the contents of each request by defining a Can Evaluate expression. Atlas evaluates the expression whenever the Function is called. If you do not specify an expression, Atlas automatically authorizes all authenticated incoming requests.
The expression can expand standard expression variables, including the %%request and %%user expansions.
例、次の式は、指定されたアドレスのリストに送信元のIPアドレスが含まれていない場合にのみ、受信リクエストを認可します。
認可式の例
{ "%%request.remoteIPAddress": { "$nin": [ "248.88.57.58", "19.241.23.116", "147.64.232.1" ] } }
プライバシーレベルを設定します。
クライアントアプリケーションが関数を参照したり呼び出したりしないようにするには、 privateをtrueに設定します。

変更を配置します。

関数の構成とソースコードをプッシュして、アプリに配置します。関数の使用をすぐに開始できます。

次のコマンドを実行して、変更を配置します。

appservices push

関数の呼び出し

別の関数または App Services CLI から関数を呼び出すことができます。

このセクションの例では、2 つの引数を受け取り、それらを加算して結果を返す sum という名前の単純な関数を呼び出す方法が示されています。

function/sum.js

// sum: adds two numbers
exports = function sum(a, b) {
  return a + b;
};

関数からの呼び出し

関数は別の関数から呼び出すことができ、任意の関数でグローバル変数として使用可能な context.functions インターフェイスを使用します。呼び出された関数は、呼び出した関数と同じコンテキスト内で実行されます。

// difference: subtracts b from a using the sum function
exports = function difference(a, b) {
  return context.functions.execute("sum", a, -1 * b);
};

App Services CLI からの呼び出し

App Services CLI のfunction runコマンドも関数の呼び出しに使用できます。このコマンドは、関数の結果を EJSON として返すほか、ログやエラーメッセージも返します。

appservices function run \
  --name=sum \
  --args=1 --args=2

By default, Functions run in the system context. To call a Function in the context of a specific user, include their User ID in the --user argument.

appservices function run \
  --name=sum \
  --args=1 --args=2 \
  --user=61a50d82532cbd0de95c7c89

制約

関数の実行時間は、リクエストごとに300秒を上限とし、その後はタイムアウトして失敗します。
関数はある時点で最大 350 MB のメモリを使用する可能性があります。
関数の非同期操作には 1,000 回の上限が設けられています。
関数は、最もよく使用されている ES6+ 機能と Node.js 組み込みモジュールをサポートしています。ただし、サーバーレスワークロードにとって一般的でないか適していない一部の機能はサポートされていません。詳細については、「JavaScript サポート」を参照してください。
関数は net 組み込みモジュールを使用して最大 25 個のソケットを開くことができます。
受信リクエストの最大サイズは18 MB に制限されています。この制限は、関数に渡されるすべての引数の合計サイズに適用されます。

戻る

trigger イベントを AWS EventBridge に送信する

Context