Azure Cosmos DB でストアド プロシージャ、トリガー、およびユーザー定義関数を登録および使用する方法

  • [アーティクル]

適用対象: NoSQL

Azure Cosmos DB の NoSQL 用 API は、JavaScript で記述されたストアド プロシージャ、トリガー、およびユーザー定義関数 (UDF) の登録および呼び出しをサポートします。 ストアド プロシージャ、トリガー、またはユーザー定義関数を 1 つ以上定義した後は、Azure portal でデータ エクスプローラーを使用してそれらを読み込み、表示することができます。

.NET v2 (レガシ)、.NET v3、Java、JavaScript、または Python などの複数の SDK プラットフォームで、NoSQL 用 API SDK を使用して該当するタスクを実行できます。 これらの SDK を使用したことがない場合は、該当する SDK のクイックスタートの記事を参照してください。

SDK 作業の開始
.NET v3 クイック スタート: .NET 用の Azure Cosmos DB for NoSQ クライアント ライブラリを使用して、次のことを行います
Java クイック スタート: Azure Cosmos DB for NoSQL のデータを管理するための Java アプリを作成する
JavaScript クイック スタート: .Node.js 用の Azure Cosmos DB for NoSQL クライアント ライブラリ
Python クイック スタート: Python 用の Azure Cosmos DB for NoSQL クライアント ライブラリを使用して、次のことを行います

重要

次のコード サンプルは、client 変数と container 変数が既にあることを前提としています。 これらの変数を作成する必要がある場合は、プラットフォームに適したクイックスタートをご覧ください。

ストアド プロシージャの実行方法

ストアド プロシージャは JavaScript を使用して記述されます。 これらは Azure Cosmos DB コンテナー内部で作成、更新、読み取り、クエリの実行、および削除できます。 詳細については、「ストアド プロシージャを記述する方法」を参照してください。

次の例では、Azure Cosmos DB SDK を使用してストアド プロシージャを登録および呼び出す方法を示します。 このストアド プロシージャ (spCreateToDoItem.js として保存) のソースについては、「ストアド プロシージャを使用して項目を作成する」を参照してください。

注意

パーティション分割されたコンテナーの場合、ストアド プロシージャを実行するとき、要求オプションにパーティション キー値を指定する必要があります。 ストアド プロシージャは常に 1 つのパーティション キーに範囲設定されます。 別のパーティション キー値を持つ項目は、ストアド プロシージャから認識できません。 この原則は、トリガーにも当てはまります。

次の例は、.NET SDK v2 を使用してストアド プロシージャを登録する方法を示しています。

string storedProcedureId = "spCreateToDoItems";
StoredProcedure newStoredProcedure = new StoredProcedure
   {
       Id = storedProcedureId,
       Body = File.ReadAllText($@"..\js\{storedProcedureId}.js")
   };
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
var response = await client.CreateStoredProcedureAsync(containerUri, newStoredProcedure);
StoredProcedure createdStoredProcedure = response.Resource;

次のコードは、.NET SDK v2 を使用してストアド プロシージャを呼び出す方法を示しています。

dynamic[] newItems = new dynamic[]
{
    new {
        category = "Personal",
        name = "Groceries",
        description = "Pick up strawberries",
        isComplete = false
    },
    new {
        category = "Personal",
        name = "Doctor",
        description = "Make appointment for check up",
        isComplete = false
    }
};

Uri uri = UriFactory.CreateStoredProcedureUri("myDatabase", "myContainer", "spCreateToDoItem");
RequestOptions options = new RequestOptions { PartitionKey = new PartitionKey("Personal") };
var result = await client.ExecuteStoredProcedureAsync<string>(uri, options, new[] { newItems });

プリトリガーの実行方法

次の例では、Azure Cosmos DB SDK を使用してプリトリガーを登録し、呼び出す方法を示します。 このプリトリガー (trgPreValidateToDoItemTimestamp.js として保存) の例のソースについては、「プリトリガー」をご覧ください。

PreTriggerInclude を指定して操作を実行し、List オブジェクトにトリガーの名前を渡すと、プリトリガーが RequestOptions オブジェクトに渡されます。

注意

トリガーの名前が List として渡される場合でも、操作ごとにトリガーを 1 つだけ実行することができます。

次のコードは、.NET SDK v2 を使用してプリトリガーを登録する方法を示しています。

string triggerId = "trgPreValidateToDoItemTimestamp";
Trigger trigger = new Trigger
{
    Id =  triggerId,
    Body = File.ReadAllText($@"..\js\{triggerId}.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Pre
};
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateTriggerAsync(containerUri, trigger);

次のコードは、.NET SDK v2 を使用してプリトリガーを呼び出す方法を示しています。

dynamic newItem = new
{
    category = "Personal",
    name = "Groceries",
    description = "Pick up strawberries",
    isComplete = false
};

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
RequestOptions requestOptions = new RequestOptions { PreTriggerInclude = new List<string> { "trgPreValidateToDoItemTimestamp" } };
await client.CreateDocumentAsync(containerUri, newItem, requestOptions);

ポストトリガーの実行方法

次の例では、Azure Cosmos DB SDK を使用してポストトリガーを登録する方法を示します。 このポストトリガー (trgPostUpdateMetadata.js として保存) の例のソースについては、「ポストトリガー」を参照してください

次のコードは、.NET SDK v2 を使用してポストトリガーを登録する方法を示しています。

string triggerId = "trgPostUpdateMetadata";
Trigger trigger = new Trigger
{
    Id = triggerId,
    Body = File.ReadAllText($@"..\js\{triggerId}.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Post
};
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateTriggerAsync(containerUri, trigger);

次のコードは、.NET SDK v2 を使用してポストトリガーを呼び出す方法を示しています。

var newItem = { 
    name: "artist_profile_1023",
    artist: "The Band",
    albums: ["Hellujah", "Rotators", "Spinning Top"]
};

RequestOptions options = new RequestOptions { PostTriggerInclude = new List<string> { "trgPostUpdateMetadata" } };
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.createDocumentAsync(containerUri, newItem, options);

ユーザー定義関数を操作する方法

次の例では、Azure Cosmos DB SDK を使用して、ユーザー定義関数を登録する方法を示します。 このユーザー定義関数 (udfTax.js として保存) の例のソースについては、「ユーザー定義関数を記述する方法」を参照してください。

次のコードは、.NET SDK v2 を使用してユーザー定義関数を登録する方法を示しています。

string udfId = "Tax";
var udfTax = new UserDefinedFunction
{
    Id = udfId,
    Body = File.ReadAllText($@"..\js\{udfId}.js")
};

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateUserDefinedFunctionAsync(containerUri, udfTax);

次のコードは、.NET SDK v2 を使用してユーザー定義関数を呼び出す方法を示しています。

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
var results = client.CreateDocumentQuery<dynamic>(containerUri, "SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000"));

foreach (var result in results)
{
    //iterate over results
}

次のステップ

Azure Cosmos DB でストアド プロシージャ、トリガー、およびユーザー定義関数を記述または作成する方法および概念について説明します。