Ćwiczenie — zapisywanie danych za pomocą powiązań wyjściowych

Ukończone

W poprzednim ćwiczeniu zaimplementowaliśmy scenariusz wyszukiwania zakładek w bazie danych usługi Azure Cosmos DB. Skonfigurowaliśmy powiązanie wejściowe w celu odczytywania danych z kolekcji zakładek. Ale możemy zrobić więcej. Rozszerzmy ten scenariusz, tak aby obejmował zapisywanie. Zapoznaj się z następującym schematem blokowym:

W tym scenariuszu otrzymujemy żądania dodania zakładek do naszej kolekcji. Żądania przekazują wymagany klucz, czyli identyfikator, wraz z adresem URL zakładki. Jak widać w schemacie blokowym, odpowiadamy z błędem, jeśli klucz już istnieje w naszym zapleczu.

Jeśli klucz przekazany do nas nie zostanie znaleziony, dodamy nową zakładkę do naszej bazy danych. Moglibyśmy zatrzymać się tutaj, lecz pójdziemy trochę dalej.

Widzisz kolejny krok w schemacie blokowym? Do tej pory nie zrobiliśmy zbyt wiele z danymi, które otrzymaliśmy pod względem przetwarzania. Przenosimy odebrane dane do bazy danych. Jednak w prawdziwym rozwiązaniu prawdopodobnie przetworzylibyśmy dane w jakiś sposób. Możemy wykonać wszystkie operacje przetwarzania w tej samej funkcji, ale w tym ćwiczeniu pokażemy wzorzec, który odciąża dalsze przetwarzanie do innego składnika lub logiki biznesowej.

Jaki może być dobry przykład odciążania pracy w naszym scenariuszu zakładek? A co jeśli wyślemy nową zakładkę do usługi generowania kodu QR? Ta usługa z kolei wygeneruje kod QR dla adresu URL, zapisze obraz w usłudze Blob Storage i doda adres obrazu QR do wpisu w kolekcji zakładek. Wywoływanie usługi w celu wygenerowania obrazu QR jest czasochłonne. Dlatego zamiast czekać na wynik, przekazujemy zadanie do funkcji i pozwalamy mu wykonać to zadanie asynchronicznie.

Podobnie jak usługa Azure Functions obsługuje powiązania wejściowe dla różnych źródeł integracji, ma również zestaw szablonów powiązań wyjściowych, dzięki czemu można łatwo zapisywać dane w źródłach danych. Powiązania wyjściowe są także skonfigurowane w pliku function.json. Jak widać w tym ćwiczeniu, możemy skonfigurować naszą funkcję do pracy z wieloma źródłami danych i usługami.

Ważne

To ćwiczenie opiera się na zasobach piaskownicy i zasobach utworzonych w poprzednich lekcjach; w szczególności baza danych, zakładki i powiązania wejściowe usługi Azure Cosmos DB. Jeśli ćwiczenia nie zostały ukończone w poprzednich lekcjach, nie będzie można ukończyć tego ćwiczenia.

Tworzenie funkcji wyzwalanej przez protokół HTTP

1. W witrynie Azure Portal przejdź do utworzonej aplikacji funkcji, wybierając nazwę aplikacji funkcji w ścieżce do stron nadrzędnych w górnej części strony funkcji HttpTrigger2 .

2. Na karcie Funkcje na stronie Przegląd powinny być utworzone funkcje wyzwalacza HTTP.

3. Wybierz pozycję Utwórz na karcie Funkcje . Zostanie wyświetlone okienko Tworzenie funkcji .

4. W sekcji Wybierz szablon wybierz pozycję Wyzwalacz HTTP, a następnie wybierz pozycję Dalej. Zaakceptuj wartości domyślne na karcie Szczegóły szablonu i wybierz pozycję Utwórz. Zostanie wyświetlone okienko Przegląd funkcji HttpTrigger3 .

Dodawanie powiązania wejściowego usługi Azure Cosmos DB

Dodajmy kolejne powiązanie wejściowe usługi Azure Cosmos DB.

1. W menu Funkcja HttpTrigger3 wybierz pozycję Integracja. Zostanie wyświetlone okienko Integracja .

2. W polu Wyzwalacz i dane wejściowe wybierz pozycję Dodaj dane wejściowe. Zostanie wyświetlone okienko Tworzenie danych wejściowych .

3. Z listy rozwijanej Typ powiązania wybierz pozycję Azure Cosmos DB.

4. Ustawienie połączenia konta usługi Cosmos DB powinno zostać wstępnie wypełnione połączeniem utworzonym w poprzednim ćwiczeniu.

   Jeśli nie widzisz połączenia na liście, wykonaj następujące kroki, aby utworzyć nowe połączenie.

   1. W sekcji Szczegóły usługi Azure Cosmos DB w obszarze ustawienia połączenia konta usługi Cosmos DB wybierz link Nowy.

   2. Po wyświetleniu okna dialogowego Nowe połączenie usługi Cosmos DB wybierz przycisk OK , aby utworzyć połączenie. Zostanie utworzone nowe połączenie konta usługi Cosmos DB.

5. Wprowadź następujące wartości dla innych ustawień w tym okienku. W dowolnym momencie, aby dowiedzieć się więcej na temat przeznaczenia ustawienia, możesz wybrać ikonę informacji po prawej stronie.

   Ustawienie	Wartość	Opis
   Nazwa parametru dokumentu	bookmark	Nazwa używana do identyfikacji tego powiązania w kodzie.
   Nazwa bazy danych	func-io-learn-db	Baza danych, z którą będziemy pracować. Ta wartość to nazwa bazy danych ustawiona wcześniej w tej lekcji.
   Nazwa kolekcji	Bookmarks	Nazwa kolekcji, z której są odczytywane dane. To ustawienie zdefiniowaliśmy wcześniej w lekcji.
   Identyfikator dokumentu	{id}	Dodaj {id} polecenie , aby użyć poprawnego wyrażenia powiązania i zaakceptować parametr przekazany w ciągu zapytania.
   Klucz partycji	{id}	Ponownie dodaj {id} polecenie , aby użyć poprawnego wyrażenia powiązania i zaakceptować parametr przekazany w ciągu zapytania.
   Zapytanie SQL (opcjonalne)	Pozostaw puste	Pobieramy tylko jeden element na podstawie identyfikatora. Dlatego filtrowanie przy użyciu ustawienia Dokument jest lepsze niż użycie zapytania SQL w tym wystąpieniu. Możemy opracować zapytanie SQL zwracające jedną pozycję (SELECT * from b where b.ID = /id). To zapytanie rzeczywiście zwróci element, ale zwróci je w kolekcji elementów. Nasz kod musiałby niepotrzebnie manipulować kolekcją. Użyj zapytania SQL, jeśli chcesz pobrać wiele dokumentów.

   Podobnie jak powiązanie wejściowe utworzone w poprzednim ćwiczeniu, chcemy wyszukać zakładkę o określonym identyfikatorze, więc powiązaliśmy identyfikator dokumentu, który nasza funkcja otrzymuje w ciągu zapytania do powiązania, nazywanego wyrażeniem powiązania. Wyzwalacz funkcji to żądanie HTTP, które używa ciągu zapytania do określenia identyfikatora do wyszukania. Powiązanie zwraca 0 (nie znaleziono) lub 1 (znalezione) dokumenty.

6. Wybierz pozycję Dodaj , aby zapisać konfigurację powiązania wejściowego.

Mamy teraz powiązanie wejściowe usługi Azure Cosmos DB. Dodajmy powiązanie wyjściowe, abyśmy mogli zapisywać nowe wpisy w kolekcji.

Dodawanie powiązania wyjściowego usługi Azure Cosmos DB

1. W okienku Integracja dla elementu HttpTrigger3 w polu Dane wyjściowe wybierz pozycję Dodaj dane wyjściowe. Zostanie wyświetlone okienko Tworzenie danych wyjściowych .

2. W obszarze Typ powiązania z listy rozwijanej wybierz pozycję Azure Cosmos DB.

3. Ustawienie połączenia konta usługi Cosmos DB powinno zostać wstępnie wypełnione utworzonym wcześniej połączeniem. Jeśli nie, rozwiń listę rozwijaną i wybierz połączenie zdefiniowane dla powiązania wejściowego HttpTrigger3.

4. Wprowadź następujące wartości dla pozostałych ustawień powiązania wyjściowego.

   Ustawienie	Wartość	Opis
   Nazwa parametru dokumentu	newbookmark	Nazwa używana do identyfikacji tego powiązania w kodzie. Ten parametr jest używany do zapisywania nowego wpisu zakładki.
   Nazwa bazy danych	func-io-learn-db	Baza danych, z którą będziemy pracować. Ta wartość to nazwa bazy danych ustawiona wcześniej w tej lekcji.
   Nazwa kolekcji	Bookmarks	Nazwa kolekcji, z której są odczytywane dane. Ta wartość to nazwa kontenera zdefiniowana wcześniej w lekcji.
   Klucz partycji	/id	Dodaj klucz partycji, który zdefiniowaliśmy wcześniej podczas tworzenia kontenera Zakładki usługi Azure Cosmos DB. Klucz wprowadzony tutaj (określony w konfiguracji <key>powiązania wejściowego ) musi być zgodny z kluczem w kontenerze.

5. Wybierz pozycję Dodaj , aby zapisać tę konfigurację powiązania wyjściowego.

Teraz mamy powiązanie do odczytu z naszej kolekcji i powiązanie do zapisu w tej kolekcji.

Dodawanie powiązania wyjściowego usługi Azure Queue Storage

Azure Queue Storage to usługa do przechowywania komunikatów, do których można uzyskać dostęp z dowolnego miejsca na świecie. Rozmiar pojedynczego komunikatu może wynosić nawet 64 KB, a kolejka może zawierać miliony komunikatów — do całkowitej pojemności konta magazynu zdefiniowanego w kolejce. Na poniższym diagramie przedstawiono na wysokim poziomie sposób użycia kolejki w naszym scenariuszu.

W tym przykładzie widać, że funkcja o nazwie add-bookmark dodaje komunikaty do kolejki, a inny o nazwie gen-qr-code wyświetla komunikaty z tej samej kolejki i przetwarza żądanie. Ponieważ zapisujemy lub wypychamy komunikaty do kolejki z zakładki add-bookmark, dodamy nowe powiązanie wyjściowe do rozwiązania.

Utwórzmy powiązanie za pośrednictwem portalu.

1. W okienku Integracja funkcji w polu Dane wyjściowe wybierz pozycję Dodaj dane wyjściowe. Zostanie wyświetlone okienko Tworzenie danych wyjściowych .

2. Z listy rozwijanej Typ powiązania wybierz pozycję Azure Queue Storage.

   Jeśli pojawi się komunikat z monitem o zainstalowanie Microsoft.Azure.WebJobs.Extensions.Storage rozszerzenia, wybierz pozycję Zainstaluj i poczekaj na zakończenie.

Następnie skonfigurujemy połączenie konta magazynu, w którym jest hostowana nasza kolejka.

1. W obszarze Połączenie konta magazynu wybierz pozycję Nowe. Zostanie wyświetlone okno dialogowe Nowe połączenie konta magazynu.

2. Na początku tego modułu podczas tworzenia aplikacji funkcji zostało również utworzone konto magazynu. Wybierz ją z listy rozwijanej, a następnie wybierz przycisk OK.

   Ustawienie połączenia konta magazynu jest wypełniane nazwą połączenia.

Mimo że możemy zachować wartości domyślne, zmieńmy niektóre ustawienia, aby zapewnić więcej znaczenia pozostałym właściwościom.

1. Wypełnij ustawienia w okienku Tworzenie danych wyjściowych , zastępując następujące stare wartości nowymi wartościami:

   Ustawienie	Stara wartość	Nowa wartość	opis
   Nazwa parametru komunikatu	outputQueueItem	newmessage	Właściwość powiązania, która jest używana w kodzie.
   Nazwa kolejki	outqueue	bookmarks-post-process	Nazwa kolejki, w której umieszczamy zakładki, tak aby inna funkcja mogła je dalej przetwarzać.

2. Wybierz pozycję Dodaj , aby zapisać konfigurację danych wyjściowych dla usługi Azure Queue Storage.

Aktualizacja implementacji funkcji

Teraz skonfigurowaliśmy wszystkie nasze powiązania. Nadszedł czas na użycie ich w funkcji.

1. Aby otworzyć plik index.js w edytorze kodu, wybierz funkcję HttpTrigger3.

2. W menu wybierz pozycję Kod i testowanie. Zostanie wyświetlone okienko Kod i test dla funkcji.

3. Zastąp cały kod w pliku index.js kodem z poniższego fragmentu kodu, a następnie na pasku poleceń wybierz pozycję Zapisz.

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

Przeanalizujmy, co ten kod robi:

• Ponieważ funkcja zmienia dane, oczekujemy żądania HTTP typu POST i określenia danych zakładki w ramach treści żądania.
• Nasze powiązanie wejściowe usługi Azure Cosmos DB podejmie próbę pobrania dokumentu, czyli zakładki, za pomocą odebranego parametru id. Jeśli znajdzie wpis, bookmark obiekt zostanie ustawiony. Warunek if(bookmark) sprawdza, czy pozycja została znaleziona.
• Dodanie do bazy danych jest tak proste, jak ustawienie parametru context.bindings.newbookmark powiązania na nowy wpis zakładki, który utworzyliśmy jako ciąg JSON.
• Aby opublikować komunikat w kolejce, wystarczy ustawić parametr context.bindings.newmessage.

Uwaga

Jedyne wykonane przez Ciebie zadanie to utworzenie powiązania kolejki. Kolejka nie została utworzona jawnie. Jesteś świadkiem możliwości powiązań! Jak zadeklarowano w następującym powiadomieniu, kolejka zostanie utworzona automatycznie, jeśli nie istnieje.

.

1. Wybierz function.json z listy rozwijanej w <functionapp> \ HttpTrigger3 \ ścieżce i wprowadź następujące zmiany:

   1. Zmień wszystkie wystąpienia elementu "collectionName" na "containerName".
   2. Zmień wszystkie wystąpienia elementu "connectionStringSetting" na "connection".
   3. Usuń odwołania do "methods": [].

2. Końcowy plik function.json powinien przypominać ten kod.

   {
     "bindings": [
       {
         "authLevel": "function",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "methods": [
           "get",
           "post"
         ]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "name": "bookmark",
         "direction": "in",
         "type": "cosmosDB",
         "partitionKey": "{id}",
         "databaseName": "func-io-learn-db",
         "containerName": "Bookmarks",
         "connection": "your-database_DOCUMENTDB",
         "id": "{id}"
       },
       {
         "name": "newbookmark",
         "direction": "out",
         "type": "cosmosDB",
         "partitionKey": "/id",
         "databaseName": "func-io-learn-db",
         "containerName": "Bookmarks",
         "connection": "your-database_DOCUMENTDB"
       },
       {
         "name": "newmessage",
         "direction": "out",
         "type": "queue",
         "queueName": "bookmarks-post-process",
         "connection": "your-storage-account_STORAGE"
       }
     ]
   }
   

3. Na pasku poleceń wybierz pozycję Zapisz.

To wszystko. Zobaczymy naszą pracę w działaniu w następnej sekcji.

1. Aby otworzyć plik run.ps1 w edytorze kodu, wybierz funkcję HttpTrigger3 w górnej części okienka.

2. W menu Funkcja w obszarze Deweloper wybierz pozycję Kod i test. Zostanie wyświetlone okienko Kod i test dla funkcji HttpTrigger3 z domyślną zawartością elementu run.ps1.

3. Zastąp zawartość w pliku następującym kodem.

   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"
   })
   

4. Na pasku poleceń wybierz opcję Zapisz. Zostanie nawiązane połączenie, a zostanie otwarta sesja pliku dziennika.

Przeanalizujmy, co ten kod robi:

• Ponieważ funkcja zmienia dane, oczekujemy żądania HTTP typu POST i określenia danych zakładki w ramach treści żądania.
• Nasze powiązanie wejściowe usługi Azure Cosmos DB próbuje pobrać dokument lub zakładkę przy użyciu id elementu w żądaniu. Jeśli znajdzie wpis, bookmark obiekt zostanie ustawiony. Warunek if ($bookmark) sprawdza, czy pozycja została znaleziona.
• Dodawanie do bazy danych jest równie proste jak wywołanie funkcji Push-OutputBinding z nazwą powiązania wyjściowego usługi Cosmos DB (newbookmark) i wartością obiektu $newBookmark.
• Opublikowanie wiadomości w naszej kolejce jest równie proste jak wywołanie funkcji Push-OutputBinding z nazwą powiązania wyjściowego kolejki (newmessage) i wartością obiektu $newBookmark.

Uwaga

Jedyne wykonane przez Ciebie zadanie to utworzenie powiązania kolejki. Kolejka nie została utworzona jawnie. Jesteś świadkiem możliwości powiązań! Jak zadeklarowano w następującym powiadomieniu, kolejka zostanie utworzona automatycznie, jeśli nie istnieje.

To wszystko. Zobaczymy naszą pracę w działaniu w następnej sekcji.

Czas to wypróbować

Teraz, gdy mamy wiele powiązań wyjściowych, testowanie stało się nieco trudniejsze. W poprzednich lekcjach testowaliśmy zawartość, wysyłając żądanie HTTP z ciągiem zapytania, ale chcemy wykonać post HTTP tym razem. Musimy także sprawdzić, czy komunikaty docierają do kolejki.

1. Na pasku poleceń okienka Kod i test dla funkcji HttpTrigger3 wybierz pozycję Testuj/Uruchom. Zostanie wyświetlone nowe okienko z otwartą kartą Dane wejściowe, jak pokazano na poniższej ilustracji:

   

2. Na liście rozwijanej Metoda HTTP sprawdź, czy wybrano pozycję POST .

3. Zastąp zawartość treści żądania następującym obiektem JSON:

   {
       "id": "docs",
       "url": "https://learn.microsoft.com/azure"
   }
   

4. Wybierz Uruchom.

5. Postęp programowy jest wyświetlany w okienku Dzienniki . Po zakończeniu sprawdź, czy na karcie Dane wyjściowe jest wyświetlana wartość "Zakładka już istnieje". W ustawieniu zawartości odpowiedzi HTTP.

   

   Dodano element zakładki w ćwiczeniu — odczyt danych z powiązaniami wejściowymi. Odpowiedź potwierdza, że język var bookmark = context.bindings.bookmark JavaScript działa poprawnie i że kod programu PowerShell wykonuje to samo połączenie.

6. Opublikujmy drugą zakładkę w bazie danych. Wybierz kartę Dane wejściowe .

7. Zastąp zawartość treści żądania następującym obiektem JSON:

   {
       "id": "github",
       "url": "https://www.github.com"
   }
   

8. Wybierz Uruchom.

9. Sprawdź, czy na karcie Dane wyjściowe jest wyświetlana wartość "zakładka dodana!" w zawartości odpowiedzi HTTP, jak pokazano na poniższym zrzucie ekranu.

   

Gratulacje! Funkcja działa zgodnie z założeniami! Ale co z operacją kolejki dodaliśmy do kodu? Sprawdźmy, czy coś zostało zapisane do kolejki.

Weryfikowanie zapisania komunikatu do kolejki

Kolejki usługi Azure Queue Storage są hostowane na koncie magazynu. Konto magazynu zostało skonfigurowane podczas tworzenia powiązania wyjściowego.

1. Na pasku wyszukiwania globalnego witryny Azure Portal wprowadź konta magazynu, a następnie na liście wyników wybierz pozycję Konta magazynu. Zostanie wyświetlone okienko Konta magazynu.

   

2. Wybierz konto magazynu użyte do skonfigurowania powiązania danych wyjściowych newmessage .

3. W menu Konto magazynu w obszarze Magazyn danych wybierz pozycję Kolejki, aby wyświetlić listę kolejek hostowanych przez to konto magazynu. Sprawdź, czy kolejka zakładek po przetworzeniu znajduje się na liście, jak pokazano na poniższym zrzucie ekranu.

   

4. Wybierz pozycję zakładki po przetworzeniu , aby wyświetlić listę komunikatów znajdujących się w kolejce. Jeśli wszystko poszło zgodnie z planem, komunikat opublikowany przy dodawaniu zakładki do bazy danych powinien znajdować się w kolejce. Powinno to wyglądać tak.

   

   W tym przykładzie komunikat otrzymał unikatowy identyfikator, a kolumna Tekst komunikatu wyświetla zakładkę w formacie JSON. Nie ma komunikatu dotyczącego zakładki platformy Azure docs , którą próbowano dodać, ponieważ już istniała w bazie danych.

5. Funkcję można przetestować dalej, zmieniając treść żądania w okienku testowym przy użyciu nowych zestawów identyfikatorów/adresów URL i uruchamiając funkcję. Obserwuj kolejkę, aby zobaczyć kolejne przysyłane komunikaty. Możesz również przyjrzeć się bazie danych, aby sprawdzić, czy dodano nowe wpisy.

W tym ćwiczeniu rozszerzyliśmy twoją wiedzę na temat powiązań wyjściowych i zapisywaliśmy dane w usłudze Azure Cosmos DB. Dodaliśmy powiązanie wyjściowe do publikowania komunikatów w kolejce platformy Azure. W tym przykładzie pokazano prawdziwą moc powiązań, aby ułatwić kształtowanie i przenoszenie danych ze źródeł przychodzących do różnych miejsc docelowych. Nie musieliśmy pisać żadnego kodu bazy danych ani zarządzać parametry połączenia siebie. Zamiast tego skonfigurowaliśmy powiązania deklaratywnie i pozwoliliśmy platformie zabezpieczyć połączenia, skalować naszą funkcję i skalować nasze połączenia.