Übung: Schreiben von Daten mit Ausgabebindungen

15 Minuten

In der vorherigen Übung haben Sie ein Szenario implementiert, in dem es darum ging, Lesezeichen in einer Azure Cosmos DB-Datenbank nachzuschlagen. Dabei haben Sie eine Eingabebindung konfiguriert, um Daten aus der Lesezeichensammlung zu lesen. Wir können aber noch mehr tun. Erweitern wir das Szenario um Schreiben. Betrachten Sie das folgende Flussdiagramm:

Decision flow diagram illustrating the process of adding a bookmark in Azure Cosmos DB back-end and returning a response.

In diesem Szenario erhalten wir Anforderungen zum Hinzufügen von Lesezeichen zu unserer Sammlung. Die Anforderungen enthalten den gewünschten Schlüssel oder die gewünschte ID und die Lesezeichen-URL. Wie Sie im Flussdiagramm sehen können, reagieren wir mit einer Fehlermeldung, wenn der Schlüssel bereits in unserem Back-End existiert.

Wenn der Schlüssel, der uns übergeben wurde, nicht gefunden wird, fügen wir das neue Lesezeichen zu unserer Datenbank hinzu. Dabei könnten es Sie es an dieser Stelle theoretisch belassen, doch im Folgenden führen Sie noch einige zusätzliche Schritte aus.

Vielleicht ist Ihnen ein weiterer Prozess im Flussdiagramm aufgefallen. Bislang haben wir mit den Daten, die wir erhalten, in Bezug auf die Verarbeitung nicht viel unternommen. Die empfangenen Daten werden einfach in die Datenbank geschrieben. In einer echten Lösung würden jedoch wahrscheinlich eine Art der Datenverarbeitung erfolgen. Wir können die gesamte Verarbeitung in der gleichen Funktion durchführen. In dieser Übung zeigen wir stattdessen ein Muster, das die weitere Verarbeitung an eine andere Komponente oder einen Teil der Geschäftslogik auslagert.

Vermutlich fragen Sie sich, an welcher Stelle in Ihrem Lesezeichenszenario eine solche Auslagerung Sinn ergibt. Ein gutes Beispiel hierfür ist das Senden eines Lesezeichens an einen Erstellungsdienst für einen QR-Code. Dieser Dienst erstellt dann einen QR-Code für die URL, speichert das Bild in Blob Storage und fügt die Adresse des QR-Bilds in den Eintrag Ihrer Textmarkensammlung ein. Das Aufrufen eines Dienstes zum Generieren eines QR-Codes ist zeitaufwändig. Anstatt also auf das Ergebnis zu warten, geben wir die Aufgabe an eine Funktion weiter und lassen sie diese Aufgabe asynchron erledigen.

Azure Functions unterstützt nicht nur Eingabebindungen für verschiedene Integrationsquellen, sondern verfügt auch über mehrere Vorlagen für Ausgabebindungen, mit denen Sie Daten problemlos in Datenquellen schreiben können. Ausgabebindungen können auch in der Datei function.json konfiguriert werden. Wie Sie in dieser Übung sehen, können wir unsere Funktion so konfigurieren, dass sie mit mehreren Datenquellen und Diensten arbeitet.

Wichtig

Diese Übung baut auf den Sandboxressourcen und den Ressourcen auf, die Sie in vorherigen Lerneinheiten erstellt haben, insbesondere auf der Azure Cosmos DB-Datenbank, den Lesezeichen und den Eingabebindungen. Wenn Sie die Übungen in den vorherigen Lektionen noch nicht abgeschlossen haben, können Sie diese Übung nicht abschließen.

Erstellen einer durch HTTP ausgelösten Funktion

Wechseln Sie im Azure-Portal zur Funktions-App, die Sie erstellt haben, indem Sie den Namen der Funktions-App im Breadcrumb-Pfad ganz oben auf der Seite der HttpTrigger2-Funktion auswählen.
Auf der Registerkarte Funktionen auf der Seite Übersicht sollten Sie über die HTTP-Triggerfunktionen verfügen, die Sie erstellt haben.
Wählen Sie auf der Registerkarte Funktionen die Option Erstellen aus. Der Bereich Funktion erstellen wird angezeigt.
Wählen Sie unter dem Abschnitt Vorlage auswählen die Option HTTP-Trigger aus, und wählen Sie dann Erstellen aus. Der Bereich „Überblick“ der HttpTrigger3-Funktion wird angezeigt.

Hinzufügen einer Azure Cosmos DB-Eingabebindung

Fügen Sie eine weitere Azure Cosmos DB-Eingabebindung hinzu.

Wählen Sie im Menü der HttpTrigger3-Funktion die Option Integration aus. Dann wird der Bereich Integration angezeigt.
Wählen Sie im Feld Eingaben die Option Eingabe hinzufügen aus. Der Bereich Eingabe erstellen wird geöffnet.
Wählen Sie in der Dropdownliste Bindungstyp die Option Azure Cosmos DB aus.
Die Einstellung Cosmos DB-Kontoverbindung sollte mit der Verbindung vorbelegt sein, die Sie in der vorherigen Übung erstellt haben.

Wenn Ihre Verbindung nicht aufgeführt ist, führen Sie die folgenden Schritte aus, um eine neue Verbindung zu erstellen.
1. Wählen Sie im Abschnitt Azure Cosmos DB-Details unter der Einstellung Cosmos DB-Kontoverbindung den Link Neu aus.
2. Wenn das Dialogfeld Neue Cosmos DB-Verbindung angezeigt wird, wählen Sie OK aus, um die Verbindung zu erstellen. Eine neue Cosmos DB-Kontoverbindung wird erstellt.

Geben Sie die folgenden Werte für die anderen Einstellungen in diesem Bereich ein. Sie können jederzeit auf das Informationssymbol rechts neben der jeweiligen Einstellung klicken, um weitere Informationen zu dieser zu erhalten.

Einstellung	Wert	Beschreibung
Dokumentparametername	`bookmark`	Der Name, der zum Identifizieren dieser Bindung in Ihrem Code verwendet wird.
Datenbankname	`func-io-learn-db`	Die Datenbank, mit der gearbeitet werden soll. Dieser Wert stellt den Datenbanknamen dar, den wir zuvor in dieser Lektion festgelegt haben.
Sammlungsname	`Bookmarks`	Der Name der Sammlung, aus der die Daten gelesen werden. Diese Einstellung wurde zuvor in dieser Lektion definiert.
Dokument-ID	`{id}`	Fügen Sie `{id}` hinzu, um den richtigen Bindungsausdruck zu verwenden und den Parameter zu akzeptieren, der in der Abfragezeichenfolge übergeben wird.
Partitionsschlüssel	`{id}`	Fügen Sie erneut `{id}` hinzu, um den richtigen Bindungsausdruck zu verwenden und den Parameter zu akzeptieren, der in der Abfragezeichenfolge übergeben wird.
SQL-Abfrage (optional)	Nicht ausfüllen	Wir rufen jeweils nur ein Element basierend auf der ID ab. Daher ist die Filterung anhand der Dokumenteinstellung in diesem Fall besser als die Verwendung einer SQL-Abfrage. Wir könnten eine SQL-Abfrage für die Rückgabe eines Eintrags (`SELECT * from b where b.ID = /id`) erstellen. Diese Abfrage würde tatsächlich ein Element zurückgeben, aber es würde in einer Elementsammlung zurückgegeben werden. Unser Code müsste eine Sammlung unnötigerweise bearbeiten. Verwenden Sie den SQL-Abfrageansatz, wenn mehrere Dokumente abgerufen werden sollen.

Wie bei der Eingabebindung, die wir in der vorherigen Übung erstellt haben, möchten wir eine Textmarke mit einer bestimmten ID suchen. Daher haben wir die Document ID, die unsere Funktion empfängt, in der Abfragezeichenfolge an die Bindung gebunden. Dies wird als Bindungsausdruck bezeichnet. Der Funktionsauslöser ist eine HTTP-Anforderung, die eine Abfragezeichenfolge verwendet, um die zu suchende ID anzugeben. Die Bindung gibt entweder 0 (nicht gefunden) oder 1 (gefunden) Dokumente zurück.

Wählen Sie OK aus, um diese Eingabebindungskonfiguration zu speichern.

Wir verfügen jetzt über eine Azure Cosmos DB-Eingabebindung. Nun fügen wir eine Ausgabebindung hinzu, damit wir neue Einträge in unsere Sammlung schreiben können.

Hinzufügen einer Azure Cosmos DB-Ausgabebindung

Wählen Sie im Bereich Integration für HttpTrigger3 die Option Ausgabe hinzufügen im Feld Ausgaben aus. Der Bereich Ausgabe erstellen wird geöffnet.
Wählen Sie in der Dropdownliste unter Bindungstyp die Option Azure Cosmos DB aus.
Die Einstellung Cosmos DB-Kontoverbindung sollte mit der zuvor erstellten Verbindung vorausgefüllt sein. Falls dies nicht der Fall ist, erweitern Sie die Dropdownliste, und wählen Sie die Verbindung aus, die Sie für die HttpTrigger3-Eingabebindung definiert haben.

Geben Sie die folgenden Werte für die verbleibenden Einstellungen der Ausgabebindung ein.

Einstellung	Wert	Beschreibung
Dokumentparametername	`newbookmark`	Der Name, der zum Identifizieren dieser Bindung in Ihrem Code verwendet wird. Dieser Parameter wird verwendet, um einen neuen Lesezeicheneintrag zu schreiben.
Datenbankname	`func-io-learn-db`	Die Datenbank, mit der gearbeitet werden soll. Dieser Wert stellt den Datenbanknamen dar, den wir zuvor in dieser Lektion festgelegt haben.
Sammlungsname	`Bookmarks`	Der Name der Sammlung, aus der die Daten gelesen werden. Dieser Wert ist der Name des Containers, den wir zuvor in dieser Lektion definiert haben.
Partitionsschlüssel	`/id`	Fügen Sie den Partitionsschlüssel hinzu, den wir zuvor bei der Erstellung des Azure Cosmos DB-Containers Bookmarks definiert haben. Der hier eingegebene Schlüssel (in der Eingabebindungskonfiguration `<key>` angegeben) muss dem im Container entsprechen.

Wählen Sie OK aus, um diese Ausgabebindungskonfiguration zu speichern.

Jetzt verfügen wir über eine Bindung, um aus der Sammlung zu lesen, und über eine, um darin zu schreiben.

Hinzufügen einer Azure Queue Storage-Ausgabebindung

Azure Queue Storage ist ein Dienst zur Speicherung von Nachrichten, auf die von jedem Ort der Welt aus zugegriffen werden kann. Eine einzelne Nachricht kann bis zu 64 KB groß sein, und eine Warteschlange kann Millionen von Nachrichten enthalten. Die maximale Anzahl ist nur durch die Kapazität des Speicherkontos begrenzt. Die folgende Abbildung zeigt einen allgemeinen Überblick über die Verwendung einer Warteschlange in diesem Szenario.

Illustration showing a storage queue with a function pushing and another function popping messages.

In diesem Beispiel sehen Sie, dass eine Funktion namens add-bookmark Nachrichten zu einer Warteschlange hinzufügt, und eine andere Funktion namens gen-qr-code Nachrichten aus derselben Warteschlange entfernt und die Anforderung verarbeitet. Da wir Nachrichten in die Warteschlange schreiben bzw. pushen (von add-bookmark aus), fügen wir Ihrer Lösung eine neue Ausgabebindung hinzu.

Erstellen Sie nun die Bindung über das Portal.

Wählen Sie im Bereich Integration für Ihre Funktion die Option Ausgabe hinzufügen im Feld Ausgaben aus. Der Bereich Ausgabe erstellen wird geöffnet.
Wählen Sie in der Dropdownliste Bindungstyp die Option Azure Queue Storage aus.

Wenn Sie in einer Meldung aufgefordert werden, die Erweiterung Microsoft.Azure.WebJobs.Extensions.Storage zu installieren, klicken Sie auf Installieren, und warten Sie, bis die Installation abgeschlossen ist.

Als nächstes richten wir eine Verbindung zu einem Speicherkonto ein, auf dem unsere Warteschlange gehostet wird.

Wählen Sie unter Speicherkontoverbindung die Option Neu aus. Das Dialogfeld Neue Speicherkontoverbindung wird angezeigt.
Zu Beginn dieses Moduls wurde beim Erstellen einer Funktions-App auch ein Speicherkonto für Sie erstellt. Wählen Sie dieses in der Dropdownliste aus, und wählen Sie dann OK aus.

Die Einstellung Speicherkontoverbindung wird mit dem Namen einer Verbindung gefüllt.

Auch wenn wir die Standardwerte beibehalten könnten, ändern wir einige Einstellungen, um den übrigen Eigenschaften mehr Bedeutung zu verleihen.

Vervollständigen Sie die Einstellungen im Bereich Ausgabe erstellen, indem Sie die folgenden alten Werte durch die neuen Werte ersetzen:

Einstellung	Alter Wert	Neuer Wert	Beschreibung
Name des Meldungsparameters	outputQueueItem	newmessage	Die Bindungseigenschaft, die wir im Code verwenden.
Warteschlangenname	outqueue	bookmarks-post-process	Der Name der Warteschlange, in der wir die Lesezeichen ablegen, damit eine andere Funktion sie weiterverarbeiten kann.

Klicken Sie auf OK, um Ihre Ausgabekonfiguration für Azure Queue Storage zu speichern.

Aktualisieren der Funktionsimplementierung

Nun sind alle Bindungen eingerichtet. Verwenden wir diese nun in unserer Funktion.

Wählen Sie Ihre Funktion (HttpTrigger3) aus, um die Datei index.js im Code-Editor zu öffnen.
Klicken Sie Menü unter Entwickler auf Programmieren und testen. Der Bereich Codieren und testen wird für Ihre Funktion angezeigt.

Ersetzen Sie den gesamten Code in der Datei index.js durch den Code aus dem folgenden Codeausschnitt, und wählen Sie dann in der Befehlsleiste Speichern aus.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark;
    if(bookmark){
            context.res = {
            status: 422,
            body : "Bookmark already exists.",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    else {
        
        // Create a JSON string of our bookmark.
        var bookmarkString = JSON.stringify({ 
            id: req.body.id,
            url: req.body.url
        });

        // Write this bookmark to our database.
        context.bindings.newbookmark = bookmarkString;

        // Push this bookmark onto our queue for further processing.
        context.bindings.newmessage = bookmarkString;

        // Tell the user all is well.
        context.res = {
            status: 200,
            body : "bookmark added!",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    context.done();
};

Betrachten wir nun, welchen Zweck der Code im Einzelnen erfüllt:

Da die Funktion Ihre Daten ändert, ist zu erwarten, dass es sich um eine HTTP-POST-Anforderung handelt und die Lesezeichendaten Teil des Anforderungstexts sind.
Über die Azure Cosmos DB-Eingabebindung wird versucht, ein Dokument oder Lesezeichen mithilfe der empfangenen id abzurufen. Wenn ein Eintrag gefunden wird, wird das bookmark-Objekt festgelegt. Mit der Bedingung if(bookmark) wird überprüft, ob ein Eintrag gefunden wurde.
Sie können der Datenbank ganz einfach ein Lesezeichen hinzufügen. Hierzu legen Sie nur den context.bindings.newbookmark-Bindungsparameter auf den neuen Lesezeicheneintrag fest, den Sie als JSON-Zeichenfolge erstellt haben.
Wenn Sie den Parameter context.bindings.newmessage festlegen, können Sie außerdem problemlos Nachrichten an Ihre Warteschlange übermitteln.

Hinweis

Diese Ergebnisse konnten Sie einfach durch das Erstellen einer Warteschlangenbindung erzielen. Die Warteschlange musste nicht explizit erstellt werden. Hieran wird erkennbar, wie leistungsfähig Bindungen sind. Wie die folgende Benachrichtigung deklariert, wird die Warteschlange automatisch erstellt, wenn sie nicht vorhanden ist.

Screenshot showing message that the queue will be auto-created. .

Fertig! Im nächsten Abschnitt sehen Sie, wie das bisher Umgesetzte beim Testen aussieht.

Wählen Sie Ihre HttpTrigger3-Funktion aus dem Breadcrumb-Pfad ganz oben im Bereich aus, um die Datei run.ps1 im Code-Editor zu öffnen.
Klicken Sie Menü „Funktion“ unter Entwickler auf Programmieren und testen. Der Bereich Programmieren und testen wird für Ihre HttpTrigger3-Funktion angezeigt und zeigt den Standardinhalt von run.ps1 an.

Ersetzen Sie den Inhalt in der Datei durch den folgenden Code.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = 422
    $body = "Bookmark already exists."
}
else {
    $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }

    Push-OutputBinding -Name newbookmark -Value $newBookmark

    Push-OutputBinding -Name newmessage -Value $newBookmark

    $status = [HttpStatusCode]::OK
    $body = "bookmark added!"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
    ContentType = "application/json"
})

Klicken Sie auf der Befehlsleiste auf Speichern. Es wird eine Verbindung hergestellt und eine Protokolldateisitzung geöffnet.

Betrachten wir nun, welchen Zweck der Code im Einzelnen erfüllt:

Da die Funktion Ihre Daten ändert, ist zu erwarten, dass es sich um eine HTTP-POST-Anforderung handelt und die Lesezeichendaten Teil des Anforderungstexts sind.
Über die Azure Cosmos DB-Eingabebindung wird versucht, ein Dokument oder Lesezeichen mithilfe von id in der Anforderung abzurufen. Wenn ein Eintrag gefunden wird, wird das bookmark-Objekt festgelegt. Mit der Bedingung if ($bookmark) wird überprüft, ob ein Eintrag gefunden wurde.
Das Hinzufügen von Elementen zu der Datenbank ist genauso einfach wie das Aufrufen von Push-OutputBinding mit dem Namen der Ausgabebindung für Cosmos DB (newbookmark) und dem Wert des Objekts $newBookmark.
Das Senden von Nachrichten an unsere Warteschlange ist genauso einfach wie das Aufrufen von Push-OutputBinding mit dem Namen der Warteschlangenausgabe für (newmessage) und dem Wert des Objekts $newBookmark.

Hinweis

Screenshot showing UI tool tip that the queue will be auto-created.

Fertig! Im nächsten Abschnitt sehen Sie, wie das bisher Umgesetzte beim Testen aussieht.

Ausprobieren

Da nun mehrere Ausgabebindungen vorhanden sind, werden die Tests etwas komplizierter. In den vorangegangenen Lektionen haben wir uns damit begnügt, eine HTTP-Anforderung mit einer Abfragezeichenfolge zu senden, aber dieses Mal möchten wir eine HTTP-POST-Anforderung durchführen. Außerdem soll überprüft werden, ob der Warteschlange tatsächlich Nachrichten hinzugefügt werden.

Klicken Sie in der Befehlsleiste des Bereichs Programmieren und testen für Ihre HttpTrigger3Funktion auf Testen/Ausführen. Es wird wie in der folgenden Abbildung gezeigt ein neuer Bereich mit geöffneter Registerkarte „Eingabe“ angezeigt:
Stellen Sie in der Dropdownliste HTTP-Methode sicher, dass POST ausgewählt ist.
Ersetzen Sie den Inhalt des Anforderungstexts durch das folgende JSON-Objekt:
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```
Klicken Sie auf Run (Ausführen).
Der programmgesteuerte Fortschritt wird im Bereich Protokolle angezeigt. Vergewissern Sie sich nach Abschluss, dass auf der Registerkarte Ausgabe in der Einstellung HTTP-Antwortinhalt die Meldung „Bookmark already exists.“ (Lesezeichen ist bereits vorhanden) angezeigt wird.

Sie haben das Lesezeichenelement in Übung: Lesen von Daten mit Eingabebindungen hinzugefügt. Die Antwort bestätigt, dass Ihr var bookmark = context.bindings.bookmark-JavaScript ordnungsgemäß funktioniert und dass Ihr PowerShell-Code die gleiche Verbindung hergestellt hat.
Stellen wir eine zweite Textmarke in der Datenbank bereit. Wählen Sie die Registerkarte Eingabe aus.
Ersetzen Sie den Inhalt des Anforderungstexts durch das folgende JSON-Objekt:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Klicken Sie auf Run (Ausführen).
Vergewissern Sie sich, dass auf der Registerkarte Ausgabe in der Einstellung HTTP-Antwortinhalt die Meldung „bookmark added!“ (Lesezeichen hinzugefügt!) angezeigt wird. Dies wird im folgenden Screenshot gezeigt.

Herzlichen Glückwunsch! Ihre Funktion funktioniert wie vorgesehen! Aber was ist mit dem Warteschlangenvorgang, den wir dem Code hinzugefügt haben? Überprüfen Sie also, ob der Warteschlange Nachrichten hinzugefügt wurden.

Überprüfen, ob der Warteschlange eine Nachricht hinzugefügt wird

Azure Queue Storage-Warteschlangen werden in einem Speicherkonto gehostet. Sie haben das Speicherkonto konfiguriert, als Sie die Ausgabebindung erstellt haben.

Geben Sie im globalen Suchfeld des Azure-Portals Speicherkonten ein, und wählen Sie dann in der Ergebnisliste Speicherkonten aus. Der Bereich Speicherkonten wird angezeigt.
Wählen Sie das Speicherkonto aus, das Sie zum Konfigurieren der Ausgabebindung newmessage verwendet haben.
Wählen Sie im Menü Speicherkonto unter Datenspeicher die Option Warteschlangen aus, um die von diesem Speicherkonto gehosteten Warteschlangen aufzulisten. Überprüfen Sie, ob die Warteschlange bookmarks-post-process wie auf dem folgenden Screenshot dargestellt vorhanden ist.
Wählen Sie bookmarks-post-process aus, um die Nachrichten aufzulisten, die sich in der Warteschlange befinden. Wenn alles planmäßig verlaufen ist, enthält die Warteschlange die Nachricht, die Sie beim Hinzufügen eines Lesezeichens zur Datenbank veröffentlicht haben. Diese sollte wie folgt aussehen:

In diesem Beispiel wurde der Nachricht eine eindeutige ID zugewiesen, und die Spalte Nachrichtentext enthält das Lesezeichen im JSON-Format. Für das Azure docs-Lesezeichen, das Sie hinzufügen wollten, wird keine Meldung angezeigt, da es bereits in der Datenbank vorhanden war.
Sie können die Funktion noch weiter testen, indem Sie im Bereich „Testen“ innerhalb des Anforderungstexts neue IDs und URLs festlegen und die Funktion ausführen. Beobachten Sie die Warteschlange eine Zeit lang, um zu sehen, wie neue Nachrichten eintreffen. Sie können außerdem einen Blick auf die Datenbank werfen, um zu überprüfen, ob neue Einträge hinzugefügt wurden.

In dieser Übung haben Sie mehr über Bindungen und Ausgabebindungen erfahren und Daten in Ihre Azure Cosmos DB-Datenbank geschrieben. Sie haben eine Ausgabebindung hinzugefügt, um Nachrichten an eine Azure-Warteschlange zu übermitteln. Dieses Beispiel zeigt, wie leistungsfähig Bindungen sind, wenn es darum geht, Daten aus eingehenden Quellen zu formen und an verschiedene Ziele zu übertragen. Sie mussten weder Datenbankcode schreiben noch Verbindungszeichenfolgen selbst verwalten. Stattdessen haben Sie Bindungen deklarativ konfiguriert, wodurch die Absicherung der Verbindungen und die Skalierung der Funktion sowie der Verbindungen von der Plattform durchgeführt wurden.

Weiter