Registrieren und Verwenden von gespeicherten Prozeduren, Triggern und benutzerdefinierten Funktionen in Azure Cosmos DB

Artikel
08/15/2024

GILT FÜR: NoSQL

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 gespeicherte Prozeduren, Trigger und benutzerdefinierte Funktionen definiert haben, können Sie diese laden und im Azure-Portal mit dem Daten-Explorer anzeigen.

Sie können das SDK API for NoSQL auf mehreren Plattformen verwenden, einschließlich auf .NET v2 (Legacy),.NET v3, Java, JavaScript oder Python, um diese Aufgaben auszuführen. Wenn Sie noch nicht mit einem dieser SDKs gearbeitet haben, lesen Sie den Schnellstartartikel für das entsprechende SDK:

SDK	Erste Schritte
.NET v3	Schnellstart: Azure Cosmos DB for NoSQL-Clientbibliothek für .NET
Java	Schnellstart: Erstellen einer Java-App zum Verwalten von Azure Cosmos DB for NoSQL-Daten
JavaScript	Schnellstart: Azure Cosmos DB for NoSQL-Clientbibliothek für Node.js
Python	Schnellstart: Azure Cosmos DB for NoSQL-Clientbibliothek für Python

Wichtig

In den folgenden Codebeispielen wird davon ausgegangen, dass Sie bereits über client- und container-Variablen 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 Schreiben von gespeicherten Prozeduren.

Die folgenden Beispiele zeigen, wie Sie eine gespeicherte Prozedur mithilfe der Azure Cosmos DB SDKs registrieren und aufrufen. Den Quellcode für diese gespeicherte Prozedur (gespeichert als spCreateToDoItem.js) finden Sie unter Erstellen von Elementen mit gespeicherten Prozeduren.

Hinweis

Wenn Sie eine gespeicherte Prozedur in partitionierten Containern ausführen, muss in den Anforderungsoptionen ein Partitionsschlüsselwert angegeben werden. Gespeicherte Prozeduren gelten immer für einen bestimmten Partitionsschlüssel. Elemente, die einen anderen Partitionsschlüsselwert aufweisen, sind in der gespeicherten Prozedur nicht sichtbar. Dieses Prinzip gilt auch für Trigger.

Das folgende Beispiel zeigt, wie Sie mit dem .NET SDK v2 eine gespeicherte Prozedur 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 mit dem .NET SDK v2 eine gespeicherte Prozedur 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 mit dem .NET SDK v3 eine gespeicherte Prozedur 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 mit dem .NET SDK v3 eine gespeicherte Prozedur 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 mit dem Java SDK eine gespeicherte Prozedur registrieren:

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

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

Der folgende Code zeigt, wie Sie mit dem Java SDK eine gespeicherte Prozedur 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 mit dem JavaScript SDK eine gespeicherte Prozedur 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 Sie mit dem JavaScript SDK eine gespeicherte Prozedur aufrufen:

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 mit dem Python-SDK eine gespeicherte Prozedur 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 mit dem Python-SDK eine gespeicherte Prozedur 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)

Vorgehensweise: Ausführen von Prätriggern

Die folgenden Beispiele zeigen, wie Sie einen Prätrigger mithilfe der Azure Cosmos DB SDKs registrieren und aufrufen. Den Quellcode dieses Beispiels für Prätrigger (gespeichert unter dem Namen trgPreValidateToDoItemTimestamp.js) finden Sie unter Prätrigger.

Wenn Sie einen Vorgang ausführen, indem Sie PreTriggerInclude angeben und dann den Namen des Triggers in einem List-Objekt übergeben, werden Prätrigger im RequestOptions-Objekt übergeben.

Hinweis

Auch wenn der Name des Triggers als List übergeben wird, können Sie dennoch nur einen Trigger pro Vorgang ausführen.

Der folgende Code zeigt, wie Sie mit dem .NET SDK v2 einen Prätrigger 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 mit dem .NET SDK v2 einen Prätrigger 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 mit dem .NET SDK v3 einen Prätrigger 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 mit dem .NET SDK v3 einen Prätrigger 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 mit dem Java SDK einen Prätrigger 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 mit dem Java SDK einen Prätrigger 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 mit dem JavaScript SDK einen Prätrigger 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 mit dem JavaScript SDK einen Prätrigger 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 mit dem Python SDK einen Prätrigger 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 mit dem Python SDK einen Prätrigger aufrufen:

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

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

Ausführen von nachgestellten Triggern

Die folgenden Beispiele zeigen, wie Sie einen nachgestellten Trigger mithilfe der Azure Cosmos DB SDKs registrieren. Die Quelle dieses Beispiels für Post-Trigger (gespeichert als trgPostUpdateMetadata.js) finden Sie unter Post-Trigger.

Der folgende Code zeigt, wie Sie mit dem .NET SDK v2 einen nachgestellten Trigger 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 mit dem .NET SDK v2 einen nachgestellten Trigger 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 mit dem .NET SDK v3 einen nachgestellten Trigger 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 mit dem .NET SDK v3 einen nachgestellten Trigger 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 Sie mit dem Java SDK einen nachgestellten Trigger registrieren:

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 Sie mit dem Java SDK einen nachgestellten Trigger aufrufen:

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 Sie mit dem JavaScript SDK einen nachgestellten Trigger registrieren:

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 Sie mit dem JavaScript SDK einen nachgestellten Trigger aufrufen:

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 Sie mit dem Python SDK einen nachgestellten Trigger 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/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 Sie mit dem Python SDK einen nachgestellten Trigger aufrufen:

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

Arbeiten mit benutzerdefinierten Funktionen

Die folgenden Beispiele zeigen, wie Sie eine benutzerdefinierte Funktion mithilfe der Azure Cosmos DB SDKs registrieren. Die Quelle dieses Beispiels für benutzerdefinierte Funktionen (gespeichert als udfTax.js) finden Sie unter Schreiben von benutzerdefinierten Funktionen.

Der folgende Code zeigt, wie Sie mit dem .NET SDK v2 eine benutzerdefinierte Funktion 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 Sie mit dem .NET SDK v2 eine benutzerdefinierte Funktion aufrufen:

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 mit dem .NET SDK v3 eine benutzerdefinierte Funktion registrieren:

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

Der folgende Code zeigt, wie Sie mit dem .NET SDK v3 eine benutzerdefinierte Funktion 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 mit dem Java SDK eine benutzerdefinierte Funktion registrieren:

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

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

Der folgende Code zeigt, wie Sie mit dem Java SDK eine benutzerdefinierte Funktion aufrufen:

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 Sie mit dem JavaScript SDK eine benutzerdefinierte Funktion registrieren:

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 Sie mit dem JavaScript SDK eine benutzerdefinierte Funktion aufrufen:

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 mit dem Python SDK eine benutzerdefinierte Funktion 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 Sie mit dem Python SDK eine benutzerdefinierte Funktion aufrufen:

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

Nächste Schritte

Lernen Sie weitere Konzepte und Vorgehensweisen zum Schreiben und Verwenden von gespeicherten Prozeduren, Triggern und benutzerdefinierten Funktionen in Azure Cosmos DB kennen:

Freigeben über