Docs Menu
Docs Home
/
MongoDB Atlas
/
データのやり取り
/
トリガー

Atlas Function

項目一覧

  • 関数を使用可能なケース
  • 関数の記述方法
  • 関数の定義
  • 関数の呼び出し
  • 制約

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

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

あいさつを返す基本的な関数
exports = function(name) {
  return `Hello, ${name ?? "stranger"}!`
}

関数はサーバーレス

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

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

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

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

関数を使用可能なケース

関数はユーザーが定義した任意の 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からサーバー側の関数を新規定義できます。

1

ページに移動するFunctions

  1. Triggersページに移動します。

    1. まだ表示されていない場合は、プロジェクトを含む組織をナビゲーション バーの Organizations メニューで選択します。

    2. まだ表示されていない場合は、ナビゲーション バーの Projects メニューからプロジェクトを選択します。

    3. サイドバーで、 Services見出しの下のTriggersをクリックします。

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

  2. Linked App Service: Triggersリンクをクリックします。

  3. サイドバーで、 Build見出しの下のFunctionsをクリックします。

  4. [ Create a Functionをクリックします。 Settingsタブにはデフォルトでが表示されます。

2

新規関数の命名

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

Tip

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

3

ユーザー認証の設定

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

注意

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

認証タイプ
説明

アプリケーション認証（非推奨）

非推奨。このタイプの認証では、クライアント アプリケーションが関数を呼び出す時にログインした既存のアプリケーション ユーザー配下で関数を実行するように設定されます。関数が別の関数から呼び出された場合は、その関数から実行ユーザーを継承します。

システム

このタイプの認証では、 MongoDBのCRUDおよび集計 API へのフルアクセス権を持ち、ルール、ロール、または権限の影響を受けないシステムユーザーとして関数を実行するように構成されます。

ユーザーID （非推奨）

非推奨。このタイプの認証では、常に特定のアプリケーション ユーザーとして関数が実行されるように設定されます。

スクリプト

このタイプの認証では、定義したカスタム 関数 の結果に基づいて決定された特定のアプリケーションユーザーとして関数を実行するように構成されます。 関数は特定のユーザーのid string を返す必要があります。または、 { "runAsSystem": true }を返すことでシステムユーザーを指定することもできます。

4

関数ログの設定

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

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

5

承認式の指定

Can Evaluate式を定義することで、各リクエストの内容に基づいてリクエストを動的に認可できます。 Atlas は、関数が呼び出されるたびに式を評価します。 式を指定しない場合、Atlas は認証されたすべての受信リクエストを自動的に認可します。

式は、%%request および の展開を含む標準の%%user 式変数 を展開できます。

関数の Can Evaluate JSON 式の UI への入力
クリックして拡大します
6

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

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

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

UI でのプライベート関数の切り替え
クリックして拡大します
7

関数コードの書込み

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

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

  1. Create Functionページから、 Function Editorタブをクリックします。

  2. 関数に javascript コードを追加します。少なくとも、次の例のように、コードは exports に関数を割り当てる必要があります。

    exports = function() {
       return "Hello, world!";
    };

    注意

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

8

関数の保存

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

1

MongoDB Atlas ユーザーの認証

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

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

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

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

appservices pull --remote=<App ID>

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

3

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

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

  1. functionsディレクトリまたはサブディレクトリに.jsファイルを作成します。

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

touch functions/<FunctionName>.js

Tip

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

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

例、次の関数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 以降）機能を関数で使用できます。

4

機能の設定

ローカルアプリケーションのfunctionsディレクトリでconfig.jsonファイルを開き、新規関数の構成オブジェクトを配列に追加します。

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

{
  "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>"
}

  1. ユーザー認証を設定します。

    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": ""
      }

  2. 関数ログを設定する

    関数を実行するたびに、関数が受け取った引数をログエントリに含めるには、 disable_arg_logsをfalseに設定します。

  3. 認可式 を指定します。

    Can Evaluate式を定義することで、各リクエストの内容に基づいてリクエストを動的に認可できます。 Atlas は、関数が呼び出されるたびに式を評価します。 式を指定しない場合、Atlas は認証されたすべての受信リクエストを自動的に認可します。

    式は、%%request および の展開を含む標準の%%user 式変数 を展開できます。

    例、次の式は、指定されたアドレスのリストに送信元のIPアドレスが含まれていない場合にのみ、受信リクエストを認可します。

    認可式の例
    {
       "%%request.remoteIPAddress": {
          "$nin": [
             "248.88.57.58",
             "19.241.23.116",
             "147.64.232.1"
          ]
       }
    }

  4. プライバシーレベルを設定します。

    クライアントアプリケーションが関数を参照したり呼び出したりしないようにするには、 privateをtrueに設定します。

5

変更を配置します。

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

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

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

デフォルトでは、関数はシステム コンテキストで実行されます。特定のユーザーのコンテキストで関数を呼び出すには、--user 引数にそのユーザーのユーザー ID を含めます。

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

制約

戻る

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

次へ

Context