Ćwiczenie — odczytywanie danych przy użyciu powiązań wejściowych
Załóżmy, że chcesz utworzyć usługę wyszukiwania zakładek. Początkowo usługa jest tylko do odczytu. Jeśli użytkownicy chcą znaleźć wpis, wysyłają żądanie z identyfikatorem wpisu, a nasza funkcja zwraca adres URL. Poniższy schemat blokowy ilustruje przepływ logiczny.
Gdy użytkownik wysyła żądanie z tekstem, funkcja find bookmark próbuje znaleźć wpis w bazie danych, który zawiera zakładkę z tekstem jako klucz lub identyfikator. System zwraca wynik wskazujący, czy został znaleziony wpis.
Gdy funkcja platformy Azure odbiera żądanie z identyfikatorem zakładki, najpierw sprawdza, czy żądanie jest prawidłowe. Jeśli tak nie jest, zostanie wygenerowana odpowiedź o błędzie. Jeśli żądanie jest prawidłowe, funkcja sprawdza, czy identyfikator zakładki istnieje w bazie danych usługi Azure Cosmos DB. Jeśli nie istnieje, zostanie wygenerowana odpowiedź o błędzie. Jeśli identyfikator zakładki zostanie znaleziony, generowana jest odpowiedź z informacją o powodzeniu.
Dane muszą być gdzieś przechowywane. W poprzednim schemacie blokowym magazyn danych jest wystąpieniem usługi Azure Cosmos DB. Jak jednak nawiązać połączenie z bazą danych z funkcji i odczytywać dane? W świecie funkcji w tym celu konfiguruje się powiązanie wejściowe. Konfigurowanie powiązania wejściowego za pośrednictwem witryny Azure Portal jest proste. Jak widać wkrótce, nie musisz pisać kodu ani otwierać połączenia magazynu. Te zadania zostaną wykonane za pomocą środowiska uruchomieniowego usługi Azure Functions i powiązań.
Tworzenie konta usługi Azure Cosmos DB
Uwaga
To ćwiczenie nie jest przeznaczone do samouczka dotyczącego usługi Azure Cosmos DB. Jeśli chcesz dowiedzieć się więcej, zobacz pełną ścieżkę szkoleniową dotyczącą usługi Azure Cosmos DB na końcu tego modułu.
Tworzenie konta bazy danych
Konto bazy danych jest kontenerem do zarządzania co najmniej jedną bazą danych. Zanim utworzymy bazę danych, musimy utworzyć konto bazy danych.
W menu zasobów witryny Azure Portal lub na stronie głównej wybierz pozycję Utwórz zasób. Zostanie wyświetlone okienko Tworzenie zasobu .
W menu Tworzenie zasobu wybierz pozycję Bazy danych, a następnie wyszukaj i wybierz pozycję Azure Cosmos DB. Zostanie wyświetlone okienko Który interfejs API najlepiej odpowiada twojemu obciążeniu?
W opcji Azure Cosmos DB for NoSQL wybierz pozycję Utwórz, aby utworzyć wyzwalacz usługi Cosmos DB i powiązania wejściowe/wyjściowe. Zostanie wyświetlone okienko Tworzenie konta usługi Azure Cosmos DB — Azure Cosmos DB for NoSQL .
Na karcie Podstawy wprowadź następujące wartości dla każdego ustawienia.
Ustawienie Wartość Opis Szczegóły projektu Subskrypcja Subskrypcja Concierge Subskrypcja platformy Azure, która współpracuje z zasobami w piaskownicy. Grupa zasobów Z listy rozwijanej wybierz pozycję [nazwa grupy zasobów piaskownicy] Grupa zasobów dla piaskownicy. Szczegóły wystąpienia Nazwa konta globally unique name
Wprowadź unikatową, ale rozpoznawalną nazwę konta usługi Azure Cosmos DB; documents.azure.com
jest dołączany do podanej nazwy.3 - 50 lowercase characters, numbers, or hyphens (-)
.Lokalizacja region
Wybierz najbliższy region. Zaakceptuj wartości domyślne pozostałych ustawień, a następnie wybierz pozycję Przejrzyj i utwórz , aby zweryfikować dane wejściowe. Zostanie wyświetlone powiadomienie o powodzeniu weryfikacji.
Wybierz pozycję Utwórz , aby aprowizować i wdrożyć konto bazy danych.
Wdrażanie może trochę potrwać. Przed kontynuowaniem poczekaj na komunikat Wdrożenie zakończyło się pomyślnie w centrum powiadomień.
Wybierz pozycję Przejdź do zasobu , aby przejść do konta bazy danych w portalu. Zostanie wyświetlone okienko Szybki start dla konta usługi Azure Cosmos DB.
Następnie dodamy kontener, a następnie dodamy bazę danych do konta usługi Azure Cosmos DB.
Dodawanie kontenera
W usłudze Azure Cosmos DB kontener służy do przechowywania różnych jednostek generowanych przez użytkownika, nazywanych również elementami. Tworzymy kontener o nazwie Zakładki.
Użyjmy narzędzia Eksplorator danych, aby utworzyć bazę danych i kontener.
W menu konta usługi Azure Cosmos DB wybierz pozycję Eksplorator danych. Zostanie wyświetlone okienko Eksplorator danych dla konta usługi Cosmos DB.
Wybierz pole Nowy kontener. Zostanie wyświetlone okienko Nowy kontener . Może być konieczne przewinięcie, aby go zobaczyć.
Wprowadź następujące wartości dla każdego ustawienia.
Ustawienie Wartość Opis Identyfikator bazy danych Wybierz pozycję Utwórz nową i wprowadź ciąg func-io-learn-db dla identyfikatora bazy danych Nazwy baz danych mogą mieć długość od 1 do 255 znaków i nie mogą zawierać /, \\, #, ?
spacji ani spacji końcowej.
Możesz wprowadzić dowolną wartość, ale w tym module używamy polecenia func-io-learn-db .Maksymalna liczba jednostek RU/s bazy danych 4000 Zaakceptuj domyślną przepływność 4000 jednostek żądań na sekundę (RU/s). Aby zmniejszyć opóźnienie, możesz później skalować wydajność w górę. Identyfikator kontenera Zakładki W przypadku identyfikatorów kontenerów obowiązują takie same wymagania dotyczące znaków jak dla nazw baz danych. W tym module używamy zakładek . Klucz partycji /id Klucz partycji określa, jak są dystrybuowane dokumenty w kolekcji usługi Azure Cosmos DB między partycjami danych logicznych. W tym module używamy ustawienia Klucz partycji jako wygody, ponieważ nie zajmujemy się wydajnością bazy danych w tym module. Aby dowiedzieć się więcej na temat strategii klucza partycji usługi Azure Cosmos DB, zapoznaj się z modułami usługi Microsoft Learn Azure Cosmos DB. Zaakceptuj wartości domyślne dla wszystkich pozostałych ustawień.
Przewiń do dołu okienka i wybierz przycisk OK. Poczekaj kilka minut na utworzenie bazy danych i kontenera.
Po zakończeniu Eksplorator danych wyświetla func-io-learn-db w obszarze DANE w obszarze INTERFEJS API NOSQL.
Wybierz pozycję func-io-learn-db , aby ją rozwinąć. Zwróć uwagę, że baza danych func-io-learn-db zawiera kilka elementów podrzędnych, w tym skalowanie i zakładki.
Rozwiń kontener Zakładki. Zwróć uwagę, że kilka elementów podrzędnych jest już wstępnie wypełnianych.
W następnym zadaniu do kontenera Zakładki zostaną dodane pewne dane, znane również jako elementy.
Dodawanie danych testowych
Chcesz dodać dane do kontenera Zakładki . Użyj Eksploratora danych do przechowywania adresu URL i identyfikatora dla każdego elementu.
Rozwiń bazę danych func-io-learn-db i kontener Zakładki, a następnie wybierz pozycję Elementy. Zostanie wyświetlona karta Elementy .
Na pasku poleceń wybierz pozycję Nowy element.
Zastąp domyślny kod nowego elementu następującym kodem JSON.
{ "id": "docs", "url": "https://learn.microsoft.com/azure" }
Na pasku poleceń wybierz pozycję Zapisz.
Zwróć uwagę, że zostanie wyświetlonych więcej właściwości niż dwa dodane wiersze. Wszystkie zaczynają się od podkreślonego elementu
(_rid, _self, _etag, _attachments, _ts)
. Te właściwości, opisane w poniższej tabeli, są generowane przez system, aby ułatwić zarządzanie elementami dodanymi do kontenera.Właściwości opis _rid
Identyfikator zasobu to unikatowy identyfikator, który jest również hierarchiczny dla stosu zasobów w modelu zasobów. Identyfikator jest używany wewnętrznie do umieszczania i nawigacji zasobu elementu. _self
Unikatowy adresowalny identyfikator URI zasobu. _etag
Właściwość wymagana na potrzeby optymistycznej kontroli współbieżności. _attachments
Ścieżka adresowa zasobu załączników. _ts
Sygnatura czasowa ostatniej aktualizacji tego zasobu. Dodajmy jeszcze kilka elementów do kontenera Zakładki . Na pasku poleceń wybierz pozycję Nowy element. Utwórz jeszcze cztery elementy o następującej zawartości. Dodaj elementy, wybierając pozycję Nowy element, a następnie wybierając pozycję Zapisz po skopiowaniu i wklejeniu każdego nowego elementu. Zwróć uwagę, że każdy element jest dodawany do listy elementów.
{ "id": "portal", "url": "https://portal.azure.com" }
{ "id": "learn", "url": "https://learn.microsoft.com/training" }
{ "id": "marketplace", "url": "https://azuremarketplace.microsoft.com/marketplace/apps" }
{ "id": "blog", "url": "https://azure.microsoft.com/blog" }
Po zakończeniu wprowadzania danych zakładki kontener powinien wyglądać jak na poniższej ilustracji.
Kontener Zakładek zawiera pięć elementów. W tym scenariuszu, jeśli żądanie zostanie dostarczone z ciągiem "id=docs", wyszukuje ten identyfikator w kontenerze Zakładki i zwraca adres URL https://learn.microsoft.com/azure
. Utwórzmy funkcję platformy Azure, która wyszukuje wartości w kontenerze Zakładki.
Tworzenie funkcji
Przejdź do aplikacji funkcji utworzonej w poprzedniej lekcji. W menu zasobów wybierz pozycję Strona główna, a w sekcji Ostatnie zasoby powinna zostać wyświetlona aplikacja funkcji (typ to Aplikacja funkcji). Wybierz aplikację funkcji. Zostanie wyświetlone okienko Aplikacja funkcji.
Na karcie Funkcje na stronie Przegląd powinna istnieć jedna funkcja HttpTrigger1.
Utwórzmy inną funkcję. Wybierz pozycję Utwórz na karcie Funkcje . Zostanie wyświetlone okienko Tworzenie funkcji z listą szablonów obsługiwanych wyzwalaczy.
W sekcji Wybierz szablon wybierz pozycję Wyzwalacz HTTP, a następnie wybierz pozycję Dalej.
Zaakceptuj wszystkie ustawienia domyślne i wybierz pozycję Utwórz , aby utworzyć funkcję.
Zostanie wyświetlone okienko Przegląd funkcji HttpTrigger2 .
Weryfikowanie funkcji
Postęp można sprawdzić do tej pory, testując nową funkcję.
Na pasku poleceń wybierz pozycję Pobierz adres URL funkcji. Zostanie wyświetlone okno dialogowe Pobieranie adresu URL funkcji.
Wybierz pozycję domyślną (klucz funkcji) z listy rozwijanej, a następnie wybierz ikonę Kopiuj do schowka , a następnie wybierz przycisk OK.
Wklej adres URL funkcji skopiowany na pasek adresu nowej karty przeglądarki. Dołącz wartość
&name=<your name>
ciągu zapytania na końcu adresu URL, zastępując<your name>
ciąg nazwą, a następnie naciśnij Enter. Funkcja platformy Azure powinna zwrócić spersonalizowaną odpowiedź w przeglądarce.
Teraz, gdy nasza funkcja szkieletowa działa, zwróćmy uwagę na odczytywanie danych z usługi Azure Cosmos DB lub w naszym scenariuszu z kontenera Zakładki .
Dodawanie powiązania wejściowego usługi Azure Cosmos DB
Aby móc odczytywać dane z bazy danych, należy zdefiniować powiązanie wejściowe. Jak widać tutaj, można skonfigurować powiązanie, które może komunikować się z bazą danych w zaledwie kilku krokach.
W witrynie Azure Portal w menu Funkcji HttpTrigger2 u góry wybierz pozycję Integracja. Zostanie wyświetlone okienko Integracja funkcji.
Użyto szablonu, który utworzył żądanie wyzwalacza HTTP z powiązaniem danych wyjściowych HTTP. Dodajmy powiązanie wejściowe usługi Azure Cosmos DB.
W polu Wyzwalacz i dane wejściowe wybierz pozycję Dodaj dane wejściowe. Zostanie wyświetlone okienko Tworzenie danych wejściowych .
Z listy rozwijanej Typ powiązania wybierz pozycję Azure Cosmos DB.
W sekcji Szczegóły usługi Azure Cosmos DB w obszarze ustawienia połączenia konta usługi Cosmos DB wybierz link Nowy. Zostanie wyświetlone okno dialogowe Nowe połączenie usługi Cosmos DB.
Jeśli pojawi się komunikat z monitem o zainstalowanie rozszerzenia Microsoft.Azure.WebJobs.Extensions.CosmosDB, wybierz pozycję Zainstaluj i poczekaj na zakończenie.
Domyślnie platforma Azure rozpoznaje utworzone wcześniej konto usługi Azure Cosmos DB. Wybierz przycisk OK , aby skonfigurować połączenie z bazą danych. Nowe połączenie z kontem bazy danych jest skonfigurowane i jest wyświetlane w polu Połączenie konta usługi Cosmos DB.
Chcemy wyszukać zakładkę z określonym identyfikatorem, więc powiązajmy identyfikator otrzymany w ciągu zapytania z powiązaniem.
Ukończmy ustawienia w okienku Tworzenie danych wejściowych . Wprowadź następujące wartości dla każdego ustawienia. Aby dowiedzieć się więcej na temat przeznaczenia każdego ustawienia, wybierz ikonę informacji w tym polu.
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 ustawiona nazwa bazy danych. Nazwa kolekcji Bookmarks
Kolekcja, z których odczytujemy dane. To ustawienie zostało zdefiniowane. Identyfikator dokumentu id
Dodaj identyfikator dokumentu zdefiniowany podczas tworzenia kontenera Zakładki usługi Azure Cosmos DB. Klucz partycji /id
Dodaj klucz partycji zdefiniowany podczas tworzenia kolekcji Zakładki usługi Azure Cosmos DB. Wprowadzony tutaj klucz (określony w formacie powiązania danych wejściowych <key>
) musi być zgodny z kluczem w kolekcji.Zapytanie SQL (opcjonalne) Pozostaw puste Pobierasz tylko jeden dokument na podstawie identyfikatora. Dlatego filtrowanie przy użyciu ustawienia Identyfikator dokumentu jest lepsze niż użycie zapytania SQL w tym wystąpieniu. Możesz opracować zapytanie SQL zwracające jedną pozycję ( SELECT * from b where b.ID = id
). To zapytanie rzeczywiście zwróci dokument, ale w postaci kolekcji dokumentów. Kod musiałby niepotrzebnie manipulować kolekcją. Użyj zapytania SQL, jeśli chcesz pobrać wiele dokumentów.Aby wyjaśnić, dlaczego używamy tych ustawień, chcemy wyszukać zakładkę z określonym identyfikatorem, więc powiązaliśmy identyfikator dokumentu, który nasza funkcja otrzymuje w ciągu zapytania do powiązania wejściowego. Ta składnia jest zwana wyrażeniem powiązania. Funkcja jest wyzwalana przez żądanie HTTP, które używa ciągu zapytania do określenia wyszukiwanego identyfikatora. Ponieważ identyfikatory są unikatowe w naszej kolekcji, powiązanie zwraca 0 (nie znaleziono) lub 1 (znalezione) dokumenty.
Aby zapisać tę konfigurację powiązania wejściowego, wybierz pozycję Dodaj.
Aktualizowanie implementacji funkcji
Teraz, gdy powiązanie jest zdefiniowane, możesz użyć go w funkcji. Należy wprowadzić dwie zmiany w celu zaimplementowania utworzonego powiązania:
Zmodyfikuj kod implementacji specyficzny dla języka funkcji. Należy określić, czy dokument został znaleziony w bazie danych zgodny z identyfikatorem przekazanym do funkcji.
Zmodyfikuj kod implementacji JSON funkcji, tak aby akceptował parametr przekazywany w ciągu zapytania.
Modyfikowanie kodu implementacji języka JavaScript funkcji
W menu Funkcja dla funkcji HttpTrigger2 wybierz pozycję Kod i testowanie. Zostanie wyświetlone okienko Kod i test dla funkcji HttpTrigger2 .
Zastąp cały kod w pliku index.js następującym kodem.
module.exports = function (context, req) { var bookmark = context.bindings.bookmark if(bookmark){ context.res = { body: { "url": bookmark.url }, headers: { 'Content-Type': 'application/json' } }; } else { context.res = { status: 404, body : "No bookmarks found", headers: { 'Content-Type': 'application/json' } }; } context.done(); };
Na pasku poleceń wybierz pozycję Zapisz. Wybierz pozycję Dzienniki systemu plików z listy rozwijanej w górnej części okienka dzienników (które domyślnie wyświetla dzienniki usługi App Insights). Zostanie wyświetlone okienko Dzienniki z wyświetlonym
Connected!
Sprawdźmy, co robi ten kod.
Przychodzące żądanie HTTP wyzwala funkcję i do powiązania wejściowego usługi Azure Cosmos DB jest przekazywany parametr zapytania
id
.Jeśli baza danych znajdzie dokument zgodny z tym identyfikatorem,
bookmark
parametr zostanie ustawiony na zlokalizowany dokument.W tym przykładzie kod tworzy odpowiedź zawierającą wartość adresu URL znajdującą się w odpowiednim dokumencie bazy danych.
Jeśli żaden dokument nie zostanie znaleziony pasujący do tego klucza, żądanie odpowie za pomocą ładunku i kodu stanu, który informuje użytkownika o złej wiadomości.
Modyfikowanie kodu implementacji JSON funkcji
Wybierz pozycję function.json z listy rozwijanej w
<functionapp> \ HttpTrigger2 \
ścieżce.Zastąp cały kod w pliku function.json następującym kodem. Upewnij się, że i zastąp
your-database
ciąg nazwą konta usługi Azure Cosmos DB.{ "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}", } ] }
Na pasku poleceń wybierz pozycję Zapisz.
Modyfikowanie kodu implementacji programu PowerShell funkcji
W menu Funkcja dla funkcji HttpTrigger2 wybierz pozycję Kod i testowanie. Zostanie wyświetlone okienko Kod i test dla funkcji HttpTrigger2 z wyświetlonym plikiem
run.ps1
.Zastąp cały kod w
run.ps1
pliku następującym kodem.using namespace System.Net param($Request, $bookmark, $TriggerMetadata) if ($bookmark) { $status = [HttpStatusCode]::OK $body = @{ url = $bookmark.url } } else { $status = [HttpStatusCode]::NotFound $body = "No bookmarks found" } Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ StatusCode = $status Body = $body })
Na pasku poleceń wybierz pozycję Zapisz. Wybierz pozycję Dzienniki systemu plików z listy rozwijanej w górnej części okienka dzienników (które domyślnie wyświetla dzienniki usługi App Insights). Zostanie wyświetlone okienko Dzienniki z wyświetlonym
Connected!
Sprawdźmy, co robi ten kod.
Przychodzące żądanie HTTP wyzwala funkcję i do powiązania wejściowego usługi Azure Cosmos DB jest przekazywany parametr zapytania
id
.Jeśli baza danych znajdzie dokument zgodny z tym identyfikatorem,
bookmark
parametr zostanie ustawiony na zlokalizowany dokument.W tym przykładzie kod tworzy odpowiedź zawierającą wartość adresu URL znajdującą się w odpowiednim dokumencie bazy danych.
Jeśli żaden dokument nie zostanie znaleziony pasujący do tego klucza, żądanie odpowie za pomocą ładunku i kodu stanu, który informuje użytkownika o złej wiadomości.
Modyfikowanie kodu implementacji JSON funkcji
Wybierz pozycję function.json z listy rozwijanej w
<functionapp> \ HttpTrigger2 \
ścieżce.Zmodyfikuj wartości parametru
id
ipartitionKey
tak, aby akceptowały parametr .{id}
Kod function.json powinien przypominać poniższy przykład, gdzieyour-database
jest zastępowany nazwą bazy danych Cosmos DB.{ "bindings": [ { "authLevel": "function", "type": "httpTrigger", "direction": "in", "name": "Request", "methods": [ "get", "post" ] }, { "type": "http", "direction": "out", "name": "Response" }, { "type": "cosmosDB", "name": "bookmark", "databaseName": "func-io-learn-db", "containerName": "Bookmarks", "connection": "your-database_DOCUMENTDB", "direction": "in", "id": "{id}", "partitionKey": "{id}" } ] }
Na pasku poleceń wybierz pozycję Zapisz.
Czas to wypróbować
Powinien już znajdować się w okienku Kod i test dla funkcji HttpTrigger2 .
Na pasku poleceń wybierz pozycję Pobierz adres URL funkcji. Zostanie wyświetlone okno dialogowe Pobieranie adresu URL funkcji.
Z listy rozwijanej Klucz wybierz pozycję domyślną w obszarze Klucz funkcji, a następnie wybierz ikonę Kopiuj do schowka na końcu adresu URL.
Wklej klucz funkcji skopiowany na pasek adresu nowej karty przeglądarki, a następnie dodaj wartość
&id=docs
ciągu zapytania na końcu adresu URL. Wynikowy adres URL powinien przypominać następujący przykład:https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Naciśnij Enter, aby uruchomić żądanie. Odpowiedź zwrócona przez funkcję powinna być podobna do poniższego przykładu.
{ "url": "https://learn.microsoft.com/azure" }
Zastąp ciąg
&id=docs
ciąg ,&id=missing
naciśnij Enter i obserwuj odpowiedź. Zdefiniowaliśmy pięć zakładek i utworzyliśmy zrozumiałą odpowiedź o błędzie, jeśli żądana zakładka nie istnieje.
Podczas tej lekcji utworzono ręcznie pierwsze powiązanie wejściowe na potrzeby odczytu z bazy danych usługi Azure Cosmos DB. Dzięki powiązaniom ilość kodu napisanego w celu przeszukania bazy danych i odczytu danych była minimalna. Większość pracy wykonaliśmy, konfigurując powiązanie deklaratywnie, a platforma zajmowała się resztą.
Podczas następnej lekcji dodasz więcej danych do kolekcji zakładek za pomocą powiązania wyjściowego usługi Azure Cosmos DB.