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

GILT FÜR: SQL-API

Die SQL-API 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. Sobald 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 SQL-API-SDK auf mehreren Plattformen verwenden, einschließlich den SDKs .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 Artikel Schnellstart für das entsprechende SDK:

SDK Erste Schritte
.NET v3 Schnellstart: Erstellen einer .NET-Konsolen-App zum Verwalten von Ressourcen der Azure Cosmos DB-SQL-API
Java Schnellstart: Erstellen einer Java-App zum Verwalten von Azure Cosmos DB-SQL-API-Daten
JavaScript Schnellstart: Verwenden von Node.js zum Herstellen einer Verbindung mit einem und Abfragen von Daten aus einem Azure Cosmos DB-SQL-API-Konto
Python Schnellstart: Erstellen einer Python-Anwendung mithilfe eines SQL-API-Kontos für Azure Cosmos DB

Ausführen gespeicherter Prozeduren

Gespeicherte Prozeduren werden mit JavaScript geschrieben. Sie können Elemente in einem Azure Cosmos-Container erstellen, aktualisieren, lesen, abfragen und löschen. Weitere Informationen zum Schreiben von gespeicherten Prozeduren in Azure Cosmos DB finden Sie im Artikel Schreiben von gespeicherten Prozeduren in Azure Cosmos DB.

Die folgenden Beispiele zeigen, wie Sie eine gespeicherte Prozedur mithilfe der Azure Cosmos DB SDKs registrieren und aufrufen. Informieren Sie sich unter Erstellen eines Elements, da die Quelle für diese gespeicherte Prozedur als spCreateToDoItem.js gespeichert ist.

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. Dies 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 });

Ausführen von vorangestellten Triggern

Die folgenden Beispiele zeigen, wie Sie einen vorangestellten Trigger mithilfe der Azure Cosmos DB SDKs registrieren und aufrufen. Informieren Sie sich unter Beispiel für vorangestellte Trigger, da die Quelle für diesen vorangestellten Trigger als trgPreValidateToDoItemTimestamp.js gespeichert ist.

Bei der Ausführung eines Vorgangs werden vorangestellte Trigger im RequestOptions-Objekt übergeben, indem PreTriggerInclude angegeben und dann der Name des Triggers an ein List-Objekt übergeben wird.

Hinweis

Auch wenn der Name des Triggers als List-Objekt ü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 vorangestellten 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 vorangestellten 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);

Ausführen von nachgestellten Triggern

Die folgenden Beispiele zeigen, wie Sie einen nachgestellten Trigger mithilfe der Azure Cosmos DB SDKs registrieren. Informieren Sie sich unter Beispiel für nachgestellte Trigger, da die Quelle für diesen nachgestellten Trigger als trgPostUpdateMetadata.js gespeichert ist.

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

Arbeiten mit benutzerdefinierten Funktionen

Die folgenden Beispiele zeigen, wie Sie eine benutzerdefinierte Funktion mithilfe der Azure Cosmos DB SDKs registrieren. Informieren Sie sich unter Beispiel für benutzerdefinierte Funktionen, da die Quelle für diese benutzerdefinierte Funktion als udfTax.js gespeichert ist.

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
}

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: