Erstellen von gespeicherten Prozeduren

Abgeschlossen

Azure Cosmos DB bietet eine in die Sprache integrierte transaktionale Ausführung von JavaScript, mit der Sie gespeicherte Prozeduren, Trigger und benutzerdefinierte Funktionen (User Defined Functions, UDFs) schreiben können. Zum Aufrufen einer gespeicherten Prozedur, eines Triggers oder einer benutzerdefinierten Funktion müssen Sie die jeweilige Kopmonente registrieren. Weitere Informationen finden Sie unter Arbeiten mit gespeicherten Prozeduren, Triggern und benutzerdefinierten Funktionen in Azure Cosmos DB.

Hinweis

Der Fokus dieser Lerneinheit liegt auf gespeicherten Prozeduren, in der folgenden Lerneinheit werden Trigger und benutzerdefinierte Funktionen behandelt.

Schreiben von gespeicherten Prozeduren

Gespeicherte Prozeduren können Elemente in einem Azure Cosmos DB-Container erstellen, aktualisieren, lesen, abfragen und löschen. Gespeicherte Prozeduren werden pro Auflistung registriert und können auf beliebige Dokumente und Anhänge angewendet werden, die sich in dieser Auflistung befinden.

Hier ist eine einfache gespeicherte Prozedur, die die Antwort „Hello World“ zurückgibt.

var helloWorldStoredProc = {
    id: "helloWorld",
    serverScript: function () {
        var context = getContext();
        var response = context.getResponse();

        response.setBody("Hello, World");
    }
}

Das Kontextobjekt bietet Zugriff auf alle Vorgänge, die in Azure Cosmos DB ausgeführt werden können, sowie Zugriff auf die Anforderungs- und Antwortobjekte. In diesem Fall verwenden Sie das Antwortobjekt dazu, den Text der Antwort festzulegen, der an den Client zurückgesendet werden soll.

Erstellen eines Elements mithilfe einer gespeicherten Prozedur

Wenn Sie ein Element mithilfe einer gespeicherten Prozedur erstellen, wird dieses Element in den Azure Cosmos DB-Container eingefügt, und es wird eine ID für das neu erstellte Element zurückgegeben. Das Erstellen eines Elements ist ein asynchroner Vorgang und hängt von den JavaScript-Rückruffunktionen ab. Die Rückruffunktion verfügt über zwei Parameter: einen für das Fehlerobjekt für den Fall eines Fehlers im Vorgang und einen anderen für einen Rückgabewert, in diesem Fall für das erstellte Objekt. Innerhalb des Rückrufs können Sie entweder die Ausnahme behandeln oder einen Fehler auslösen. Falls ein Rückruf nicht bereitgestellt wird und ein Fehler auftritt, löst die Azure Cosmos DB-Laufzeitumgebung einen Fehler aus.

Die gespeicherte Prozedur enthält auch einen Parameter zum Festlegen der Beschreibung. Hierbei handelt es sich um einen booleschen Wert. Wenn der Parameter auf TRUE festgelegt wird und die Beschreibung fehlt, löst die gespeicherte Prozedur eine Ausnahme aus. Andernfalls wird der Rest der gespeicherten Prozedur weiter ausgeführt.

Diese gespeicherte Prozedur übernimmt documentToCreate, den in der aktuellen Sammlung zu erstellenden Text eines Dokuments, als Eingabe. Alle derartigen Vorgänge sind asynchron und von JavaScript-Funktionsrückrufen abhängig.

var createDocumentStoredProc = {
    id: "createMyDocument",
    body: function createMyDocument(documentToCreate) {
        var context = getContext();
        var collection = context.getCollection();
        var accepted = collection.createDocument(collection.getSelfLink(),
              documentToCreate,
              function (err, documentCreated) {
                  if (err) throw new Error('Error' + err.message);
                  context.getResponse().setBody(documentCreated.id)
              });
        if (!accepted) return;
    }
}

Arrays als Eingabeparameter für gespeicherte Prozeduren

Beim Definieren einer gespeicherten Prozedur im Azure-Portal werden Eingabeparameter immer als Zeichenfolge an die gespeicherte Prozedur gesendet. Selbst wenn Sie ein Array von Zeichenfolgen als Eingabe übergeben, wird das Array in eine Zeichenfolge konvertiert und an die gespeicherte Prozedur gesendet. Zur Umgehung dieses Problems können Sie eine Funktion in Ihrer gespeicherten Prozedur definieren, mit der die Zeichenfolge als Array analysiert wird. Der folgende Code zeigt, wie ein Zeichenfolgen-Eingabeparameter als Array analysiert wird:

function sample(arr) {
    if (typeof arr === "string") arr = JSON.parse(arr);

    arr.forEach(function(a) {
        // do something here
        console.log(a);
    });
}

Gebundene Ausführung

Alle Azure Cosmos DB-Vorgänge müssen innerhalb einer begrenzten Zeit abgeschlossen werden. Die Ausführung von gespeicherten Prozeduren auf dem Server ist zeitlich begrenzt. Alle Funktionen der Auflistung geben einen booleschen Wert zurück, der angibt, ob dieser Vorgang abgeschlossen wird oder nicht.

Transaktionen in gespeicherten Prozeduren

Sie können Transaktionen mithilfe einer gespeicherten Prozedur in Elementen innerhalb eines Containers implementieren. JavaScript-Funktionen können ein fortsetzungsbasiertes Modell implementieren, damit die Ausführung in Batches erfolgt oder fortgesetzt wird. Der Fortsetzungswert kann ein beliebiger Wert Ihrer Wahl sein, und Ihre Anwendungen können diesen Wert dann verwenden, um eine Transaktion von einem neuen Startpunkt aus fortzusetzen. Das folgende Diagramm zeigt, wie das Transaktionsfortsetzungsmodell verwendet werden kann, um eine serverseitige Funktion zu wiederholen, bis die gesamte Verarbeitungsworkload der Funktion abgeschlossen ist.