Come registrare e usare stored procedure, trigger e funzioni definite dall'utente in Azure Cosmos DB

  • Articolo

SI APPLICA A: NoSQL

Con l'API for NoSQL di Azure Cosmos DB è possibile registrare e richiamare stored procedure, trigger e funzioni definite dall'utente scritte in JavaScript. Dopo aver definito uno o più trigger, stored procedure e funzioni definite dall'utente, è possibile caricarli e visualizzarli nel portale di Azure con Esplora dati.

È possibile usare API for NoSQL SDK in più piattaforme, tra cui gli SDK per .NET v2 (legacy), .NET v3, Java, JavaScripto Python per eseguire queste attività. Se non si è mai usato uno di questi SDK in precedenza, vedere l'articolo di avvio rapido per l'SDK appropriato:

SDK Introduzione
.NET v3 Avvio rapido: Libreria client di Azure Cosmos DB for NoSQL per .NET
Java Avvio rapido: Compilare un'app Java per gestire i dati di Azure Cosmos DB for NoSQL
JavaScript Avvio rapido: Libreria client di Azure Cosmos DB for NoSQL per Node.js
Python Avvio rapido: Libreria client di Azure Cosmos DB for NoSQL per Python

Importante

Gli esempi di codice seguenti presuppongono che siano già presenti le variabili client e container. Se è necessario creare queste variabili, vedere l'argomento di avvio rapido appropriato per la piattaforma in uso.

Come eseguire stored procedure

Le stored procedure vengono scritte in JavaScript Possono creare, aggiornare, leggere ed eliminare elementi all'interno di un contenitore Azure Cosmos DB, nonché eseguire query su tali elementi. Per altre informazioni, vedere Come scrivere stored procedure.

Gli esempi seguenti illustrano come registrare e chiamare una stored procedure con gli SDK di Azure Cosmos DB. Per il codice sorgente di questa stored procedure, salvato come spCreateToDoItem.js, vedere Creare elementi usando le stored procedure.

Nota

Per i contenitori partizionati, quando si esegue una stored procedure, è necessario specificare un valore della chiave di partizione nelle opzioni della richiesta. Le stored procedure hanno sempre come ambito una chiave di partizione. Gli elementi con un valore di chiave di partizione diverso non saranno visibili alla stored procedure. Questo principio vale anche per i trigger.

L'esempio seguente illustra come registrare una stored procedure con .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;

Il codice seguente illustra come chiamare una stored procedure con .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 });

Come eseguire i pre-trigger

Gli esempi seguenti illustrano come registrare e chiamare un pre-trigger con gli SDK di Azure Cosmos DB. Per il codice sorgente di questo esempio di pre-trigger, salvato come trgPreValidateToDoItemTimestamp.js, vedere Pre-trigger.

Quando si esegue un'operazione specificando PreTriggerInclude e quindi passando il nome del trigger in un oggetto List, i pre-trigger vengono passati nell'oggetto RequestOptions.

Nota

Anche se il nome del trigger viene passato comeList, sarà comunque possibile eseguire un solo trigger per ogni operazione.

Il codice seguente illustra come registrare un pre-trigger con .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);

Il codice seguente illustra come chiamare un pre-trigger con .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);

Come eseguire post-trigger

Gli esempi seguenti illustrano come registrare un post-trigger con gli SDK di Azure Cosmos DB. Per il codice sorgente di questo esempio di post-trigger, salvato come trgPostUpdateMetadata.js, vedere Post-trigger

Il codice seguente illustra come registrare un post-trigger con .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);

Il codice seguente illustra come chiamare un post-trigger con .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);

Come usare le funzioni definite dall'utente

Gli esempi seguenti illustrano come registrare una funzione definita dall'utente con gli SDK di Azure Cosmos DB. Per il codice sorgente di questo esempio di funzione definita dall'utente, salvato come udfTax.js, vedere Come scrivere funzioni definite dall'utente.

Il codice seguente illustra come registrare una funzione definita dall'utente con .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);

Il codice seguente illustra come chiamare una funzione definita dall'utente con .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
}

Passaggi successivi

Altre informazioni su come scrivere o usare stored procedure, trigger e funzioni definite dall'utente in Azure Cosmos DB: