Udostępnij za pośrednictwem


Łączenie usługi Azure Functions z usługą Azure Cosmos DB przy użyciu programu Visual Studio Code

Usługa Azure Functions umożliwia łączenie usług platformy Azure i innych zasobów z funkcjami bez konieczności pisania własnego kodu integracji. Te powiązania, które reprezentują zarówno dane wejściowe, jak i wyjściowe, są deklarowane w definicji funkcji. Dane z powiązań są podawane do funkcji jako parametry. Wyzwalacz to specjalny typ powiązania wejściowego. Chociaż funkcja ma tylko jeden wyzwalacz, może mieć wiele powiązań wejściowych i wyjściowych. Aby dowiedzieć się więcej, zobacz Pojęcia dotyczące wyzwalaczy i powiązań usługi Azure Functions.

W tym artykule pokazano, jak używać programu Visual Studio Code do łączenia usługi Azure Cosmos DB z funkcją utworzoną w poprzednim artykule Szybki start. Powiązanie wyjściowe dodawane do tej funkcji zapisuje dane z żądania HTTP do dokumentu JSON przechowywanego w kontenerze usługi Azure Cosmos DB.

Przed rozpoczęciem należy ukończyć przewodnik Szybki start: tworzenie funkcji języka C# na platformie Azure przy użyciu programu Visual Studio Code. Jeśli zasoby zostały już wyczyszczone na końcu tego artykułu, wykonaj kroki ponownie, aby ponownie utworzyć aplikację funkcji i powiązane zasoby na platformie Azure.

Przed rozpoczęciem należy ukończyć przewodnik Szybki start: tworzenie funkcji JavaScript na platformie Azure przy użyciu programu Visual Studio Code. Jeśli zasoby zostały już wyczyszczone na końcu tego artykułu, wykonaj kroki ponownie, aby ponownie utworzyć aplikację funkcji i powiązane zasoby na platformie Azure.

Przed rozpoczęciem należy ukończyć przewodnik Szybki start: tworzenie funkcji języka Python na platformie Azure przy użyciu programu Visual Studio Code. Jeśli zasoby zostały już wyczyszczone na końcu tego artykułu, wykonaj kroki ponownie, aby ponownie utworzyć aplikację funkcji i powiązane zasoby na platformie Azure.

Konfigurowanie środowiska

Przed rozpoczęciem upewnij się, że zainstalowano rozszerzenie Azure Databases dla programu Visual Studio Code.

Tworzenie konta usługi Azure Cosmos DB

Teraz utworzysz konto usługi Azure Cosmos DB jako typ konta bezserwerowego. Ten tryb oparty na użyciu sprawia, że usługa Azure Cosmos DB jest silną opcją dla obciążeń bezserwerowych.

  1. W programie Visual Studio Code wybierz pozycję Wyświetl>paletę poleceń... a następnie w palecie poleceń wyszukaj ciągAzure Databases: Create Server...

  2. Podaj następujące informacje po wyświetleniu monitów:

    Monit Wybór
    Wybieranie serwera usługi Azure Database Wybierz pozycję Core (NoSQL), aby utworzyć bazę danych dokumentów, którą można wykonać za pomocą składni SQL lub zapytania Copilot (wersja zapoznawcza) konwertując monity języka naturalnego na zapytania. Dowiedz się więcej o usłudze Azure Cosmos DB.
    Nazwa konta Wprowadź unikatową nazwę do identyfikacji konta usługi Azure Cosmos DB. Nazwa konta może używać tylko małych liter, cyfr i łączników (-) i musi mieć długość od 3 do 31 znaków.
    Wybieranie modelu pojemności Wybierz pozycję Bezserwerowe , aby utworzyć konto w trybie bezserwerowym .
    Wybierz grupę zasobów dla nowych zasobów Wybierz grupę zasobów, w której utworzono aplikację funkcji w poprzednim artykule.
    Wybieranie lokalizacji dla nowych zasobów Wybierz lokalizację geograficzną, w której będzie hostowane konto usługi Azure Cosmos DB. Użyj lokalizacji znajdującej się najbliżej Ciebie lub Twoich użytkowników, aby uzyskać najszybszy dostęp do danych.

    Po aprowizacji nowego konta w obszarze powiadomień zostanie wyświetlony komunikat.

Tworzenie bazy danych i kontenera usługi Azure Cosmos DB

  1. Wybierz ikonę platformy Azure na pasku Działań, rozwiń węzeł Zasoby>usługi Azure Cosmos DB, kliknij prawym przyciskiem myszy (Ctrl+wybierz w systemie macOS) konto, a następnie wybierz polecenie Utwórz bazę danych....

  2. Podaj następujące informacje po wyświetleniu monitów:

    Monit Wybór
    Nazwa bazy danych Wpisz my-database.
    Wprowadź i identyfikator kolekcji Wpisz my-container.
    Wprowadź klucz partycji dla kolekcji Wpisz /id jako klucz partycji.
  3. Wybierz przycisk OK , aby utworzyć kontener i bazę danych.

Aktualizowanie ustawień aplikacji funkcji

W poprzednim artykule Szybki start utworzono aplikację funkcji na platformie Azure. W tym artykule zaktualizujesz aplikację, aby zapisywała dokumenty JSON w utworzonym kontenerze usługi Azure Cosmos DB. Aby nawiązać połączenie z kontem usługi Azure Cosmos DB, musisz dodać jego parametry połączenia do ustawień aplikacji. Następnie pobierz nowe ustawienie do pliku local.settings.json, aby można było nawiązać połączenie z kontem usługi Azure Cosmos DB podczas uruchamiania lokalnego.

  1. W programie Visual Studio Code kliknij prawym przyciskiem myszy (Ctrl+wybierz w systemie macOS) na nowym koncie usługi Azure Cosmos DB i wybierz polecenie Kopiuj parametry połączenia.

    Kopiowanie parametry połączenia usługi Azure Cosmos DB

  2. Naciśnij F1 , aby otworzyć paletę poleceń, a następnie wyszukaj i uruchom polecenie Azure Functions: Add New Setting....

  3. Wybierz aplikację funkcji utworzoną w poprzednim artykule. Podaj następujące informacje po wyświetleniu monitów:

    Monit Wybór
    Wprowadź nazwę nowego ustawienia aplikacji Wpisz CosmosDbConnectionSetting.
    Wprowadź wartość parametru "CosmosDbConnectionSetting" Wklej parametry połączenia skopiowanego konta usługi Azure Cosmos DB. Możesz również skonfigurować tożsamość firmy Microsoft Entra jako alternatywę.

    Spowoduje to utworzenie ustawienia aplikacji o nazwie connection CosmosDbConnectionSetting w aplikacji funkcji na platformie Azure. Teraz możesz pobrać to ustawienie do pliku local.settings.json.

  4. Naciśnij F1 ponownie, aby otworzyć paletę poleceń, a następnie wyszukaj i uruchom polecenie Azure Functions: Download Remote Settings....

  5. Wybierz aplikację funkcji utworzoną w poprzednim artykule. Wybierz pozycję Tak, aby zastąpić istniejące ustawienia lokalne.

Spowoduje to pobranie wszystkich ustawień z platformy Azure do projektu lokalnego, w tym nowego ustawienia parametry połączenia. Większość pobranych ustawień nie jest używana podczas uruchamiania lokalnego.

Rejestrowanie rozszerzeń do wiązania

Ponieważ używasz powiązania wyjściowego usługi Azure Cosmos DB, przed uruchomieniem projektu musisz mieć zainstalowane odpowiednie rozszerzenie powiązań.

Z wyjątkiem wyzwalaczy HTTP i czasomierza powiązania są implementowane jako pakiety rozszerzeń. Uruchom następujące polecenie dotnet add package w oknie terminalu, aby dodać pakiet rozszerzenia usługi Azure Cosmos DB do projektu.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

Projekt został skonfigurowany do używania pakietów rozszerzeń, które automatycznie instalują wstępnie zdefiniowany zestaw pakietów rozszerzeń.

Użycie pakietów rozszerzeń jest włączone w pliku host.json w katalogu głównym projektu, który jest wyświetlany w następujący sposób:

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  },
  "concurrency": {
    "dynamicConcurrencyEnabled": true,
    "snapshotPersistenceEnabled": true
  },
  "extensions": {
    "cosmosDB": {
      "connectionMode": "Gateway"
    }
  }
}

Projekt został skonfigurowany do używania pakietów rozszerzeń, które automatycznie instalują wstępnie zdefiniowany zestaw pakietów rozszerzeń.

Użycie pakietów rozszerzeń jest włączone w pliku host.json w katalogu głównym projektu, który jest wyświetlany w następujący sposób:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  } 
}

Teraz możesz dodać powiązanie wyjściowe usługi Azure Cosmos DB do projektu.

Dodawanie powiązania danych wyjściowych

W projekcie biblioteki klas języka C# powiązania są definiowane jako atrybuty powiązania w metodzie funkcji.

Otwórz plik projektu HttpExample.cs i dodaj następujące klasy:

public class MultiResponse
{
    [CosmosDBOutput("my-database", "my-container",
        Connection = "CosmosDbConnectionSetting", CreateIfNotExists = true)]
    public MyDocument Document { get; set; }
    public HttpResponseData HttpResponse { get; set; }
}
public class MyDocument {
    public string id { get; set; }
    public string message { get; set; }
}

Klasa MyDocument definiuje obiekt, który jest zapisywany w bazie danych. Parametry połączenia dla konta magazynu jest ustawiana Connection przez właściwość . W takim przypadku można pominąć Connection , ponieważ używasz już domyślnego konta magazynu.

Klasa MultiResponse umożliwia zapisywanie w określonej kolekcji w usłudze Azure Cosmos DB i zwracanie komunikatu o powodzeniu HTTP. Ponieważ musisz zwrócić obiekt, należy również zaktualizować sygnaturę MultiResponse metody.

Określone atrybuty określają nazwę kontenera i nazwę nadrzędnej bazy danych. Parametry połączenia dla konta usługi Azure Cosmos DB jest ustawiana przez element CosmosDbConnectionSetting.

Atrybuty powiązania są definiowane bezpośrednio w kodzie funkcji. W konfiguracji danych wyjściowych usługi Azure Cosmos DB opisano pola wymagane dla powiązania wyjściowego usługi Azure Cosmos DB.

W tym MultiResponse scenariuszu należy dodać extraOutputs powiązanie wyjściowe do funkcji.

app.http('HttpExample', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {

Dodaj następujące właściwości do konfiguracji powiązania:

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

Atrybuty powiązania są definiowane bezpośrednio w pliku function_app.py . Dekorator służy do dodawania cosmos_db_output powiązania wyjściowego usługi Azure Cosmos DB:

@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
    container_name="my-container", connection="CosmosDbConnectionSetting")

W tym kodzie arg_name identyfikuje parametr powiązania, do którego odwołuje się kod, database_name i container_name są nazwami bazy danych i kolekcji, do których zapisuje powiązanie, i connection jest nazwą ustawienia aplikacji zawierającego parametry połączenia dla konta usługi Azure Cosmos DB, które znajduje się w CosmosDbConnectionSetting ustawieniu w pliku local.settings.json.

Dodawanie kodu korzystającego z powiązania danych wyjściowych

Zastąp istniejącą metodę Run następującym kodem:

[Function("HttpExample")]
public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpExample");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    // Return a response to both HTTP trigger and Azure Cosmos DB output binding.
    return new MultiResponse()
    {
         Document = new MyDocument
        {
            id = System.Guid.NewGuid().ToString(),
            message = message
        },
        HttpResponse = response
    };
}

Dodaj kod, który używa obiektu powiązania wyjściowego extraInputs do context wysyłania dokumentu JSON do nazwanej funkcji powiązania danych wyjściowych. sendToCosmosDb Dodaj ten kod przed instrukcją return .

context.extraOutputs.set(sendToCosmosDb, {
  // create a random ID
  id:
    new Date().toISOString() + Math.random().toString().substring(2, 10),
  name: name,
});

W tym momencie funkcja powinna wyglądać następująco:

const { app, output } = require('@azure/functions');

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

app.http('HttpExampleToCosmosDB', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {
    try {
      context.log(`Http function processed request for url "${request.url}"`);

      const name = request.query.get('name') || (await request.text());

      if (!name) {
        return { status: 404, body: 'Missing required data' };
      }

      // Output to Database
      context.extraOutputs.set(sendToCosmosDb, {
        // create a random ID
        id:
          new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name,
      });

      const responseMessage = name
        ? 'Hello, ' +
          name +
          '. This HTTP triggered function executed successfully.'
        : 'This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.';

      // Return to HTTP client
      return { body: responseMessage };
    } catch (error) {
      context.log(`Error: ${error}`);
      return { status: 500, body: 'Internal Server Error' };
    }
  },
});

Ten kod zwraca MultiResponse teraz obiekt zawierający zarówno dokument, jak i odpowiedź HTTP.

Zaktualizuj plik HttpExample\function_app.py , aby był zgodny z poniższym kodem. outputDocument Dodaj parametr do definicji funkcji i outputDocument.set() w instrukcji if name: :

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", container_name="my-container", connection="CosmosDbConnectionSetting")
def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
     logging.info('Python HTTP trigger function processed a request.')
     logging.info('Python Cosmos DB trigger function processed a request.')
     name = req.params.get('name')
     if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

     if name:
        outputDocument.set(func.Document.from_dict({"id": name}))
        msg.set(name)
        return func.HttpResponse(f"Hello {name}!")
     else:
        return func.HttpResponse(
                    "Please pass a name on the query string or in the request body",
                    status_code=400
                )

Dokument {"id": "name"} jest tworzony w kolekcji bazy danych określonej w powiązaniu.

Lokalne uruchamianie funkcji

Program Visual Studio Code integruje się z narzędziami Azure Functions Core, aby umożliwić uruchamianie tego projektu na lokalnym komputerze deweloperów przed opublikowaniem na platformie Azure. Jeśli nie masz jeszcze zainstalowanych lokalnie narzędzi Core Tools, zostanie wyświetlony monit o zainstalowanie go po raz pierwszy podczas uruchamiania projektu.

  1. Aby wywołać funkcję, naciśnij F5 , aby uruchomić projekt aplikacji funkcji. Na panelu Terminal są wyświetlane dane wyjściowe z narzędzi Core Tools. Aplikacja zostanie uruchomiona na panelu Terminal . Punkt końcowy adresu URL funkcji wyzwalanej przez protokół HTTP jest widoczny lokalnie.

    Zrzut ekranu przedstawiający dane wyjściowe funkcji lokalnej programu Visual Studio Code.

    Jeśli nie masz jeszcze zainstalowanych narzędzi Core Tools, po wyświetleniu monitu wybierz pozycję Zainstaluj , aby zainstalować narzędzia Core Tools.
    Jeśli masz problemy z działaniem w systemie Windows, upewnij się, że domyślny terminal programu Visual Studio Code nie jest ustawiony na powłokę WSL Bash.

  2. Po uruchomieniu narzędzi Core Tools przejdź do obszaru Azure: Functions . W obszarze Funkcje rozwiń węzeł Funkcje lokalnego projektu>. Kliknij prawym przyciskiem myszy (Windows) lub Ctrl — kliknij funkcję (macOS), HttpExample a następnie wybierz polecenie Wykonaj funkcję teraz....

    Zrzut ekranu przedstawiający funkcję execute teraz z programu Visual Studio Code.

  3. W treści żądania Enter naciśnij Enter, aby wysłać komunikat żądania do funkcji.

  4. Gdy funkcja jest wykonywana lokalnie i zwraca odpowiedź, w programie Visual Studio Code jest zgłaszane powiadomienie. Informacje o wykonywaniu funkcji są wyświetlane na panelu Terminal .

  5. Naciśnij Ctrl + C , aby zatrzymać narzędzia Core Tools i odłączyć debuger.

Lokalne uruchamianie funkcji

  1. Podobnie jak w poprzednim artykule, naciśnij F5 , aby uruchomić projekt aplikacji funkcji i narzędzia Core Tools.

  2. Po uruchomieniu narzędzi Core Tools przejdź do obszaru Azure: Functions . W obszarze Funkcje rozwiń węzeł Funkcje lokalnego projektu>. Kliknij prawym przyciskiem myszy (kliknij na komputerze Mac) HttpExample funkcję, a następnie wybierz polecenie Wykonaj funkcję teraz....

    Wykonaj funkcję teraz z programu Visual Studio Code

  3. W polu Wprowadź treść żądania zostanie wyświetlona wartość treści komunikatu { "name": "Azure" }żądania . Naciśnij Enter, aby wysłać ten komunikat żądania do funkcji.

  4. Po powrocie odpowiedzi naciśnij Ctrl + C , aby zatrzymać narzędzia Core Tools.

Sprawdź, czy dokument JSON został utworzony

  1. W witrynie Azure Portal wróć do konta usługi Azure Cosmos DB i wybierz pozycję Eksplorator danych.

  2. Rozwiń bazę danych i kontener, a następnie wybierz pozycję Elementy , aby wyświetlić listę dokumentów utworzonych w kontenerze.

  3. Sprawdź, czy nowy dokument JSON został utworzony przez powiązanie wyjściowe.

    Sprawdzanie, czy nowy dokument został utworzony w kontenerze usługi Azure Cosmos DB

Ponowne wdrażanie i weryfikowanie zaktualizowanej aplikacji

  1. W programie Visual Studio Code naciśnij F1, aby otworzyć paletę poleceń. W palecie poleceń wyszukaj i wybierz pozycję Azure Functions: Deploy to function app....

  2. Wybierz aplikację funkcji utworzoną w pierwszym artykule. Ponieważ ponownie wdrażasz projekt w tej samej aplikacji, wybierz pozycję Wdróż , aby odrzucić ostrzeżenie dotyczące zastępowania plików.

  3. Po zakończeniu wdrażania możesz ponownie użyć funkcji Execute Function Now... w celu wyzwolenia funkcji na platformie Azure.

  4. Ponownie sprawdź dokumenty utworzone w kontenerze usługi Azure Cosmos DB, aby sprawdzić, czy powiązanie wyjściowe ponownie generuje nowy dokument JSON.

Czyszczenie zasobów

Na platformie Azure zasoby odnoszą się do aplikacji funkcji, funkcji, kont magazynu itd. Są one grupowane w grupy zasobów i można usunąć wszystkie elementy w grupie, usuwając grupę.

Aby ukończyć te przewodniki Szybki start, zostały utworzone zasoby. Opłaty za te zasoby mogą być naliczane w zależności od stanu konta i cen usług. Jeśli nie potrzebujesz już tych zasobów, oto jak możesz je usunąć:

  1. W programie Visual Studio Code naciśnij F1 , aby otworzyć paletę poleceń. W palecie poleceń wyszukaj i wybierz pozycję Azure: Open in portal.

  2. Wybierz aplikację funkcji i naciśnij Enter. Strona aplikacji funkcji zostanie otwarta w witrynie Azure Portal.

  3. Na karcie Przegląd wybierz nazwany link obok pozycji Grupa zasobów.

    Zrzut ekranu przedstawiający wybieranie grupy zasobów do usunięcia ze strony aplikacji funkcji.

  4. Na stronie Grupa zasobów przejrzyj listę uwzględnionych zasobów i sprawdź, czy są to te, które chcesz usunąć.

  5. Wybierz pozycję Usuń grupę zasobów, a następnie postępuj zgodnie z instrukcjami.

    Usuwanie może potrwać kilka minut. Po jego zakończeniu przez kilka sekund będzie widoczne powiadomienie. Możesz również wybrać ikonę dzwonka w górnej części strony, aby wyświetlić powiadomienie.

Następne kroki

Zaktualizowano funkcję wyzwalaną przez protokół HTTP, aby zapisywać dokumenty JSON w kontenerze usługi Azure Cosmos DB. Teraz możesz dowiedzieć się więcej na temat tworzenia funkcji przy użyciu programu Visual Studio Code: