ストアド プロシージャを作成する

完了

Azure Cosmos DB では、統合された JavaScript 言語によるトランザクション実行が可能なため、開発者は、ストアド プロシージャ、トリガー、ユーザー定義関数 (UDF) を記述できます。 ストアド プロシージャ、トリガー、またはユーザー定義関数を呼び出すには、それを登録する必要があります。 詳細については、Azure Cosmos DB でストアド プロシージャ、トリガー、およびユーザー定義関数を操作する方法に関する記事を参照してください。

注意

このユニットでは、ストアド プロシージャに重点を置いています。次のユニットでは、トリガーとユーザー定義関数について説明します。

ストアド プロシージャを記述する

ストアド プロシージャでは、Azure Cosmos コンテナー内の項目を作成、更新、読み取り、クエリ実行、および削除できます。 ストアド プロシージャは、コレクションごとに登録され、そのコレクションに存在するあらゆるドキュメントまたは添付ファイルに作用します。

これは "Hello World" 応答を返す単純なストアド プロシージャです。

var helloWorldStoredProc = {
    id: "helloWorld",
    serverScript: function () {
        var context = getContext();
        var response = context.getResponse();

        response.setBody("Hello, World");
    }
}

コンテキスト オブジェクトを使用すると、Azure Cosmos DB で実行可能なすべての操作へのアクセス権と、要求オブジェクトと応答オブジェクトへのアクセス権が付与されます。 ここでは、応答オブジェクトを使用して、クライアントに送り返される応答の本文を設定します。

ストアド プロシージャを使用して項目を作成する

ストアド プロシージャを使用して項目を作成すると、項目は Azure Cosmos DB コンテナーに挿入され、新しく作成された項目の ID が返されます。 項目の作成は非同期操作で、JavaScript コールバック関数に依存します。 コールバック関数には、操作が失敗した場合のエラー オブジェクト用と戻り値用 (この例では作成されたオブジェクト用) の 2 つのパラメーターがあります。 コールバック内では、例外を処理することも、エラーをスローすることもできます。 コールバックが提供されていない場合にエラーが発生すると、Azure Cosmos DB ランタイムはエラーをスローします。

ストアド プロシージャには、説明を設定するパラメーターも含まれており、このパラメーターはブール値です。 パラメーターが true に設定されているときに説明が存在しないと、ストアド プロシージャは例外をスローします。 そうでない場合、ストアド プロシージャの残りの部分が引き続き実行されます。

このストアド プロシージャは、入力として documentToCreate を受け取ります。これは、現在のコレクション内に作成するドキュメントの本文を示します。 このような操作はすべて非同期に実行され、JavaScript 関数コールバックに依存します。

var createDocumentStoredProc = {
    id: "createMyDocument",
    body: function createMyDocument(documentToCreate) {
        var context = getContext();
        var collection = context.getCollection();
        var accepted = collection.createDocument(collection.getSelfLink(),
              documentToCreate,
              function (err, documentCreated) {
                  if (err) throw new Error('Error' + err.message);
                  context.getResponse().setBody(documentCreated.id)
              });
        if (!accepted) return;
    }
}

ストアド プロシージャの入力パラメーターとしての配列

Azure portal でストアド プロシージャを定義する場合、入力パラメーターは常に文字列としてストアド プロシージャに送信されます。 入力として文字列の配列を渡す場合でも、配列は文字列に変換されてストアド プロシージャに送信されます。 これを解決するため、ストアド プロシージャ内に関数を定義し、文字列を配列として解析できます。 次のコードは、文字列入力パラメーターを配列として解析する方法を示しています。

function sample(arr) {
    if (typeof arr === "string") arr = JSON.parse(arr);

    arr.forEach(function(a) {
        // do something here
        console.log(a);
    });
}

制限された実行

すべての Azure Cosmos DB 操作は、限られた時間内に完了する必要があります。 ストアド プロシージャは、サーバー上で実行される時間が限られています。 すべてのコレクション関数により、その操作が完了するかどうかを表すブール値が返されます

ストアド プロシージャ内でのトランザクション

ストアド プロシージャを使用して、コンテナー内の項目にトランザクションを実装できます。 JavaScript 関数により、continuation ベースのモデルを実装して、実行をバッチ処理または再開できます。 continuation 値に任意の値を指定でき、次に、アプリケーションでこの値を使用して、新しい開始点からトランザクションを再開できます。 次の図は、トランザクション継続モデルをどのように使用すれば、サーバー側関数がその処理ワークロード全体を完了するまで関数を繰り返すことができるかを示しています。