Die API für NoSQL in Azure Cosmos DB unterstützt das Registrieren und Aufrufen von gespeicherten Prozeduren, Triggern und benutzerdefinierten Funktionen (USER-Defined Functions, UDFs), die in JavaScript geschrieben wurden. Nachdem Sie eine oder mehrere gespeicherte Prozeduren, Trigger oder UDFs definiert haben, können Sie sie mithilfe des Daten-Explorers im Azure-Portal laden und anzeigen.
Sie können die API für NoSQL SDK auf mehreren Plattformen verwenden, einschließlich .NET v2 (Legacy), .NET v3, Java, JavaScript oder Python-SDKs, um diese Aufgaben auszuführen. Wenn Sie noch nicht mit einem dieser SDKs gearbeitet haben, lesen Sie den Schnellstartartikel für das entsprechende SDK:
Von Bedeutung
In den folgenden Codebeispielen wird davon ausgegangen, dass Sie bereits über die Variablen client und container verfügen. Wenn Sie diese Variablen erstellen müssen, lesen Sie die entsprechende Schnellstartanleitung für Ihre Plattform.
Ausführen gespeicherter Prozeduren
Gespeicherte Prozeduren werden mit JavaScript geschrieben. Sie können Elemente in einem Azure Cosmos DB-Container erstellen, aktualisieren, lesen, abfragen und löschen. Weitere Informationen finden Sie unter Gespeicherte Prozeduren schreiben.
Die folgenden Beispiele zeigen, wie Sie eine gespeicherte Prozedur mithilfe der Azure Cosmos DB-SDKs registrieren und aufrufen. Die Quelle dieses Beispiels, die als spCreateToDoItem.jsgespeichert wurde, finden Sie unter Erstellen von Elementen mithilfe gespeicherter Prozeduren.
Hinweis
Bei partitionierten Containern müssen Sie beim Ausführen einer gespeicherten Prozedur einen Partitionsschlüsselwert in den Anforderungsoptionen angeben. Gespeicherte Prozeduren sind immer auf einen Partitionsschlüssel bezogen. Elemente mit einem anderen Partitionsschlüsselwert sind für die gespeicherte Prozedur nicht sichtbar. Dieses Prinzip gilt auch für Auslöser.
Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur mithilfe des .NET SDK v2 registrieren:
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;
Der folgende Code zeigt, wie Sie eine gespeicherte Prozedur mithilfe des .NET SDK v2 aufrufen:
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 });
Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur mithilfe des .NET SDK v3 registrieren:
string storedProcedureId = "spCreateToDoItems";
StoredProcedureResponse storedProcedureResponse = await client.GetContainer("myDatabase", "myContainer").Scripts.CreateStoredProcedureAsync(new StoredProcedureProperties
{
Id = storedProcedureId,
Body = File.ReadAllText($@"..\js\{storedProcedureId}.js")
});
Der folgende Code zeigt, wie Sie eine gespeicherte Prozedur mithilfe des .NET SDK v3 aufrufen:
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 });
Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur mithilfe des Java SDK registrieren:
CosmosStoredProcedureProperties definition = new CosmosStoredProcedureProperties(
"spCreateToDoItems",
Files.readString(Paths.get("createToDoItems.js"))
);
CosmosStoredProcedureResponse response = container
.getScripts()
.createStoredProcedure(definition);
Der folgende Code zeigt, wie sie eine gespeicherte Prozedur mithilfe des Java SDK aufrufen:
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
);
Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur mithilfe des JavaScript SDK registrieren:
const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
await container.scripts.storedProcedures.create({
id: sprocId,
body: require(`../js/${sprocId}`)
});
Der folgende Code zeigt, wie eine gespeicherte Prozedur mithilfe des JavaScript SDK aufgerufen wird:
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});
Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur mithilfe des Python SDK registrieren:
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)
Der folgende Code zeigt, wie sie eine gespeicherte Prozedur mithilfe des Python SDK aufrufen:
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)
So führen Sie Vorabtrigger aus
Die folgenden Beispiele zeigen, wie Sie einen Vorabtrigger mithilfe der Azure Cosmos DB-SDKs registrieren und aufrufen. Die Quelle dieses Vorabauslöserbeispiels, die als trgPreValidateToDoItemTimestamp.jsgespeichert wurde, finden Sie unter "Pre-Triggers".
Wenn Sie einen Vorgang ausführen, indem Sie PreTriggerInclude angeben und dann den Namen des Triggers in einem List Objekt übergeben, werden Vorab-Trigger in dem RequestOptions Objekt übergeben.
Hinweis
Obwohl der Name des Triggers als List übergeben wird, können Sie immer noch pro Vorgang nur einen Trigger ausführen.
Der folgende Code zeigt, wie Sie einen Vorabauslöser mithilfe des .NET SDK v2 registrieren:
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);
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des .NET SDK v2 aufrufen:
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);
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des .NET SDK v3 registrieren:
await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
Id = "trgPreValidateToDoItemTimestamp",
Body = File.ReadAllText("@..\js\trgPreValidateToDoItemTimestamp.js"),
TriggerOperation = TriggerOperation.Create,
TriggerType = TriggerType.Pre
});
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des .NET SDK v3 aufrufen:
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" } });
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des Java SDK registrieren:
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);
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des Java SDK aufrufen:
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);
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des JavaScript SDK registrieren:
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"
});
Der folgende Code zeigt, wie Sie einen Vorabtrigger mit dem JavaScript SDK aufrufen:
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]});
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des Python-SDKs registrieren:
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)
Der folgende Code zeigt, wie Sie einen Vorabtrigger mithilfe des Python-SDKs aufrufen:
item = {'category': 'Personal', 'name': 'Groceries',
'description': 'Pick up strawberries', 'isComplete': False}
result = container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')
Wie man Post-Trigger ausführt
Die folgenden Beispiele zeigen, wie Sie einen Posttrigger mithilfe der Azure Cosmos DB-SDKs registrieren. Informationen zur Quelle dieses Posttriggerbeispiels, gespeichert als trgPostUpdateMetadata.js, finden Sie unter Posttrigger
Der folgende Code zeigt, wie Sie einen Posttrigger mithilfe des .NET SDK v2 registrieren:
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);
Der folgende Code zeigt, wie Sie einen Posttrigger mithilfe des .NET SDK v2 aufrufen:
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);
Der folgende Code zeigt, wie Sie einen Posttrigger mithilfe des .NET SDK v3 registrieren:
await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
Id = "trgPostUpdateMetadata",
Body = File.ReadAllText(@"..\js\trgPostUpdateMetadata.js"),
TriggerOperation = TriggerOperation.Create,
TriggerType = TriggerType.Post
});
Der folgende Code zeigt, wie Sie einen Posttrigger mithilfe des .NET SDK v3 aufrufen:
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" } });
Der folgende Code zeigt, wie ein Posttrigger mithilfe des Java SDK registriert wird:
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);
Der folgende Code zeigt, wie ein Posttrigger mithilfe des Java SDK aufgerufen wird:
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);
Der folgende Code zeigt, wie ein Posttrigger mithilfe des JavaScript SDK registriert wird:
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"
});
Der folgende Code zeigt, wie ein Posttrigger mithilfe des JavaScript SDK aufgerufen wird:
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]});
Der folgende Code zeigt, wie ein Posttrigger mithilfe des Python SDK registriert wird:
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)
Der folgende Code zeigt, wie ein Posttrigger mithilfe des Python SDK aufgerufen wird:
item = {'category': 'Personal', 'name': 'Groceries',
'description': 'Pick up strawberries', 'isComplete': False}
container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')
So arbeiten Sie mit benutzerdefinierten Funktionen
Die folgenden Beispiele zeigen, wie Sie eine UDF mithilfe der Azure Cosmos DB-SDKs registrieren. Informationen zur Quelle dieses Beispiels, die als udfTax.js gespeichert wurde, finden Sie unter Wie man benutzerdefinierte Funktionen schreibt.
Der folgende Code zeigt, wie Sie eine benutzerdefinierte Funktion mithilfe des .NET SDK v2 registrieren:
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);
Der folgende Code zeigt, wie eine benutzerdefinierte Funktion mithilfe des .NET SDK v2 aufgerufen wird:
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
}
Der folgende Code zeigt, wie Sie eine benutzerdefinierte Funktion mithilfe des .NET SDK v3 registrieren:
await client.GetContainer("database", "container").Scripts.CreateUserDefinedFunctionAsync(new UserDefinedFunctionProperties
{
Id = "Tax",
Body = File.ReadAllText(@"..\js\Tax.js")
});
Der folgende Code zeigt, wie sie eine benutzerdefinierte Funktion mithilfe des .NET SDK v3 aufrufen:
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
}
}
Der folgende Code zeigt, wie Sie eine benutzerdefinierte Funktion mithilfe des Java SDK registrieren:
CosmosUserDefinedFunctionProperties definition = new CosmosUserDefinedFunctionProperties(
"udfTax",
Files.readString(Paths.get("tax.js"))
);
CosmosUserDefinedFunctionResponse response = container
.getScripts()
.createUserDefinedFunction(definition);
Der folgende Code zeigt, wie eine benutzerdefinierte Funktion mithilfe des Java SDK aufgerufen wird:
CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
CosmosPagedIterable<ToDoItem> iterable = container.queryItems(
"SELECT t.cost, udf.udfTax(t.cost) AS costWithTax FROM t",
options,
ToDoItem.class);
Der folgende Code zeigt, wie eine benutzerdefinierte Funktion mithilfe des JavaScript SDK registriert wird:
const container = client.database("myDatabase").container("myContainer");
const udfId = "Tax";
await container.userDefinedFunctions.create({
id: udfId,
body: require(`../js/${udfId}`)
Der folgende Code zeigt, wie eine benutzerdefinierte Funktion mithilfe des JavaScript SDK aufgerufen wird:
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();
Der folgende Code zeigt, wie Sie eine benutzerdefinierte Funktion mithilfe des Python SDK registrieren:
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)
Der folgende Code zeigt, wie eine benutzerdefinierte Funktion mithilfe des Python SDK aufgerufen wird:
results = list(container.query_items(
'query': 'SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000'))
Nächste Schritte