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

[アーティクル]
08/15/2024

適用対象: 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 });

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

string storedProcedureId = "spCreateToDoItems";
StoredProcedureResponse storedProcedureResponse = await client.GetContainer("myDatabase", "myContainer").Scripts.CreateStoredProcedureAsync(new StoredProcedureProperties
{
    Id = storedProcedureId,
    Body = File.ReadAllText($@"..\js\{storedProcedureId}.js")
});

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

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
    }
};

var result = await client.GetContainer("database", "container").Scripts.ExecuteStoredProcedureAsync<string>("spCreateToDoItem", new PartitionKey("Personal"), new[] { newItems });

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

CosmosStoredProcedureProperties definition = new CosmosStoredProcedureProperties(
    "spCreateToDoItems", 
    Files.readString(Paths.get("createToDoItems.js"))
);

CosmosStoredProcedureResponse response = container
    .getScripts()
    .createStoredProcedure(definition);

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

CosmosStoredProcedure sproc = container   
    .getScripts()
    .getStoredProcedure("spCreateToDoItems");

List<Object> items = new ArrayList<Object>();

ToDoItem firstItem = new ToDoItem();
firstItem.category = "Personal";
firstItem.name = "Groceries";
firstItem.description = "Pick up strawberries";
firstItem.isComplete = false;
items.add(firstItem);

ToDoItem secondItem = new ToDoItem();
secondItem.category = "Personal";
secondItem.name = "Doctor";
secondItem.description = "Make appointment for check up";
secondItem.isComplete = true;
items.add(secondItem);

CosmosStoredProcedureRequestOptions options = new CosmosStoredProcedureRequestOptions();
options.setPartitionKey(
    new PartitionKey("Personal")
);

CosmosStoredProcedureResponse response = sproc.execute(
    items, 
    options
);

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

const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
await container.scripts.storedProcedures.create({
    id: sprocId,
    body: require(`../js/${sprocId}`)
});

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

const newItem = [{
    category: "Personal",
    name: "Groceries",
    description: "Pick up strawberries",
    isComplete: false
}];
const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
const {resource: result} = await container.scripts.storedProcedure(sprocId).execute(newItem, {partitionKey: newItem[0].category});

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

import azure.cosmos.cosmos_client as cosmos_client

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/spCreateToDoItems.js') as file:
    file_contents = file.read()

sproc = {
    'id': 'spCreateToDoItem',
    'serverScript': file_contents,
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
created_sproc = container.scripts.create_stored_procedure(body=sproc)

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

import uuid

new_id= str(uuid.uuid4())

# Creating a document for a container with "id" as a partition key.

new_item =   {
      "id": new_id, 
      "category":"Personal",
      "name":"Groceries",
      "description":"Pick up strawberries",
      "isComplete":False
   }
result = container.scripts.execute_stored_procedure(sproc=created_sproc,params=[new_item], partition_key=new_id)

プリトリガーの実行方法

次の例では、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);

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

await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
    Id = "trgPreValidateToDoItemTimestamp",
    Body = File.ReadAllText("@..\js\trgPreValidateToDoItemTimestamp.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Pre
});

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

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

await client.GetContainer("database", "container").CreateItemAsync(newItem, null, new ItemRequestOptions { PreTriggers = new List<string> { "trgPreValidateToDoItemTimestamp" } });

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

CosmosTriggerProperties definition = new CosmosTriggerProperties(
    "preValidateToDoItemTimestamp",
    Files.readString(Paths.get("validateToDoItemTimestamp.js"))
);
definition.setTriggerOperation(TriggerOperation.CREATE);
definition.setTriggerType(TriggerType.PRE);

CosmosTriggerResponse response = container
    .getScripts()
    .createTrigger(definition);

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

ToDoItem item = new ToDoItem();
item.category = "Personal";
item.name = "Groceries";
item.description = "Pick up strawberries";
item.isComplete = false;
    
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setPreTriggerInclude(
    Arrays.asList("preValidateToDoItemTimestamp")
);

CosmosItemResponse<ToDoItem> response = container.createItem(item, options);

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

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPreValidateToDoItemTimestamp";
await container.scripts.triggers.create({
    id: triggerId,
    body: require(`../js/${triggerId}`),
    triggerOperation: "create",
    triggerType: "pre"
});

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

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPreValidateToDoItemTimestamp";
await container.items.create({
    category: "Personal",
    name: "Groceries",
    description: "Pick up strawberries",
    isComplete: false
}, {preTriggerInclude: [triggerId]});

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

import azure.cosmos.cosmos_client as cosmos_client
from azure.cosmos import documents

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/trgPreValidateToDoItemTimestamp.js') as file:
    file_contents = file.read()

trigger_definition = {
    'id': 'trgPreValidateToDoItemTimestamp',
    'serverScript': file_contents,
    'triggerType': documents.TriggerType.Pre,
    'triggerOperation': documents.TriggerOperation.All
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
trigger = container.scripts.create_trigger(trigger_definition)

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

item = {'category': 'Personal', 'name': 'Groceries',
        'description': 'Pick up strawberries', 'isComplete': False}

result = container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')

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

次の例では、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);

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

await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
    Id = "trgPostUpdateMetadata",
    Body = File.ReadAllText(@"..\js\trgPostUpdateMetadata.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Post
});

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

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

await client.GetContainer("database", "container").CreateItemAsync(newItem, null, new ItemRequestOptions { PostTriggers = new List<string> { "trgPostUpdateMetadata" } });

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

CosmosTriggerProperties definition = new CosmosTriggerProperties(
    "postUpdateMetadata",
    Files.readString(Paths.get("updateMetadata.js"))
);
definition.setTriggerOperation(TriggerOperation.CREATE);
definition.setTriggerType(TriggerType.POST);

CosmosTriggerResponse response = container
    .getScripts()
    .createTrigger(definition);

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

ToDoItem item = new ToDoItem();
item.category = "Personal";
item.name = "Doctor";
item.description = "Make appointment for check up";
item.isComplete = true;
    
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setPostTriggerInclude(
    Arrays.asList("postUpdateMetadata")
);

CosmosItemResponse<ToDoItem> response = container.createItem(item, options);

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

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPostUpdateMetadata";
await container.scripts.triggers.create({
    id: triggerId,
    body: require(`../js/${triggerId}`),
    triggerOperation: "create",
    triggerType: "post"
});

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

const item = {
    name: "artist_profile_1023",
    artist: "The Band",
    albums: ["Hellujah", "Rotators", "Spinning Top"]
};
const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPostUpdateMetadata";
await container.items.create(item, {postTriggerInclude: [triggerId]});

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

import azure.cosmos.cosmos_client as cosmos_client
from azure.cosmos import documents

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/trgPostValidateToDoItemTimestamp.js') as file:
    file_contents = file.read()

trigger_definition = {
    'id': 'trgPostValidateToDoItemTimestamp',
    'serverScript': file_contents,
    'triggerType': documents.TriggerType.Post,
    'triggerOperation': documents.TriggerOperation.All
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
trigger = container.scripts.create_trigger(trigger_definition)

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

item = {'category': 'Personal', 'name': 'Groceries',
        'description': 'Pick up strawberries', 'isComplete': False}
container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')

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

次の例では、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
}

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

await client.GetContainer("database", "container").Scripts.CreateUserDefinedFunctionAsync(new UserDefinedFunctionProperties
{
    Id = "Tax",
    Body = File.ReadAllText(@"..\js\Tax.js")
});

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

var iterator = client.GetContainer("database", "container").GetItemQueryIterator<dynamic>("SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000");
while (iterator.HasMoreResults)
{
    var results = await iterator.ReadNextAsync();
    foreach (var result in results)
    {
        //iterate over results
    }
}

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

CosmosUserDefinedFunctionProperties definition = new CosmosUserDefinedFunctionProperties(
    "udfTax",
    Files.readString(Paths.get("tax.js"))
);

CosmosUserDefinedFunctionResponse response = container
    .getScripts()
    .createUserDefinedFunction(definition);

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

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();

CosmosPagedIterable<ToDoItem> iterable = container.queryItems(
    "SELECT t.cost, udf.udfTax(t.cost) AS costWithTax FROM t", 
    options, 
    ToDoItem.class);

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

const container = client.database("myDatabase").container("myContainer");
const udfId = "Tax";
await container.userDefinedFunctions.create({
    id: udfId,
    body: require(`../js/${udfId}`)

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

const container = client.database("myDatabase").container("myContainer");
const sql = "SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000";
const {result} = await container.items.query(sql).toArray();

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

import azure.cosmos.cosmos_client as cosmos_client

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/udfTax.js') as file:
    file_contents = file.read()
udf_definition = {
    'id': 'Tax',
    'serverScript': file_contents,
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
udf = container.scripts.create_user_defined_function(udf_definition)

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

results = list(container.query_items(
    'query': 'SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000'))

次のステップ

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

次の方法で共有

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

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

プリトリガーの実行方法

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

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

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

プリトリガーの実行方法

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

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

次のステップ

フィードバック

その他のリソース

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

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