Udostępnij za pośrednictwem

Samouczek: dodawanie połączenia bazy danych usługi Azure Cosmos DB w usłudze Azure Static Web Apps (wersja zapoznawcza)

  • Artykuł

Z tego samouczka dowiesz się, jak połączyć bazę danych Usługi Azure Cosmos DB for NoSQL z statyczną aplikacją internetową. Po skonfigurowaniu można wysyłać żądania GraphQL do wbudowanego /data-api punktu końcowego w celu manipulowania danymi bez konieczności pisania kodu zaplecza.

Dla uproszczenia w tym samouczku pokazano, jak używać bazy danych platformy Azure do celów programowania lokalnego, ale możesz również użyć lokalnego serwera bazy danych do lokalnych potrzeb programistycznych.

Uwaga

W tym samouczku pokazano, jak używać usługi Azure Cosmos DB for NoSQL. Jeśli chcesz użyć innej bazy danych, zapoznaj się z samouczkami usługi Azure SQL, MySQL lub PostgreSQL .

Przeglądarka internetowa przedstawiająca wyniki z usługi Cosmos DB w oknie konsoli narzędzi deweloperskich.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Łączenie bazy danych Azure Cosmos DB for NoSQL ze statyczną aplikacją internetową
  • Tworzenie, odczytywanie, aktualizowanie i usuwanie danych

Wymagania wstępne

Aby ukończyć ten samouczek, musisz mieć istniejącą bazę danych Azure Cosmos DB for NoSQL i statyczną aplikację internetową.

Zasób opis
Usługa Azure Cosmos DB dla bazy danych NoSQL Jeśli jeszcze go nie masz, wykonaj kroki opisane w przewodniku Tworzenie bazy danych usługi Azure Cosmos DB.
Istniejąca statyczna aplikacja internetowa Jeśli jeszcze go nie masz, wykonaj kroki opisane w przewodniku wprowadzającym , aby utworzyć statyczną aplikację internetową No Framework .

Zacznij od skonfigurowania bazy danych do pracy z funkcją połączenia bazy danych usługi Azure Static Web Apps.

Konfigurowanie łączności z bazą danych

Usługa Azure Static Web Apps musi mieć dostęp sieciowy do bazy danych, aby połączenia z bazą danych działały. Ponadto aby używać bazy danych platformy Azure do programowania lokalnego, należy skonfigurować bazę danych tak, aby zezwalała na żądania z własnego adresu IP.

  1. Przejdź do konta usługi Azure Cosmos DB for NoSQL w witrynie Azure Portal.

  2. W sekcji Ustawienia wybierz opcję Sieć.

  3. W sekcji Dostęp publiczny wybierz pozycję Wszystkie sieci. Ta akcja umożliwia użycie bazy danych w chmurze na potrzeby programowania lokalnego, do której wdrożony zasób usługi Static Web Apps może uzyskiwać dostęp do bazy danych, i że można wysyłać zapytania do bazy danych z portalu.

  4. Wybierz pozycję Zapisz.

Pobieranie parametry połączenia bazy danych na potrzeby programowania lokalnego

Aby użyć bazy danych platformy Azure do programowania lokalnego, musisz pobrać parametry połączenia bazy danych. Jeśli planujesz używać lokalnej bazy danych do celów programistycznych, możesz pominąć ten krok.

  1. Przejdź do konta usługi Azure Cosmos DB for NoSQL w witrynie Azure Portal.

  2. W sekcji Ustawienia wybierz pozycję Klucze.

  3. W polu PODSTAWOWE PARAMETRY POŁĄCZENIA skopiuj parametry połączenia i odłóż ją w edytorze tekstów.

Tworzenie danych przykładowych

Utwórz przykładową tabelę i utwórz ją z przykładowymi danymi, aby dopasować ją do samouczka.

  1. W oknie nawigacji po lewej stronie wybierz pozycję Eksplorator danych.

  2. Wybierz pozycję Nowy kontener. Wprowadź identyfikator bazy danych jako Create new, a następnie wprowadź MyTestPersonDatabase jako wartość.

  3. Wprowadź identyfikator kontenera .MyTestPersonContainer

  4. Wprowadź klucz partycji ( id ta wartość jest poprzedzona prefiksem /).

  5. Wybierz przycisk OK.

  6. Wybierz kontener MyTestPersonContainer.

  7. Wybierz jego elementy.

  8. Wybierz pozycję Nowy element i wprowadź następującą wartość:

    {
    "id": "1",
    "Name": "Sunny"
}

Konfigurowanie statycznej aplikacji internetowej

W pozostałej części tego samouczka skupiono się na edytowaniu kodu źródłowego statycznej aplikacji internetowej w celu lokalnego korzystania z połączeń z bazą danych.

Ważne

W poniższych krokach założono, że pracujesz z statyczną aplikacją internetową utworzoną w przewodniku wprowadzającym. Jeśli używasz innego projektu, pamiętaj, aby dostosować następujące polecenia git, aby dopasować nazwy gałęzi.

  1. Przejdź do main gałęzi .

    git checkout main

  2. Zsynchronizuj lokalną wersję z funkcjami usługi GitHub przy użyciu polecenia git pull.

    git pull origin main

Tworzenie pliku konfiguracji bazy danych

Następnie utwórz plik konfiguracji używany przez statyczną aplikację internetową do interfejsu z bazą danych.

  1. Otwórz terminal i utwórz nową zmienną do przechowywania parametry połączenia. Określona składnia może się różnić w zależności od używanego typu powłoki.

    export DATABASE_CONNECTION_STRING='<YOUR_CONNECTION_STRING>'

    Pamiętaj, aby zastąpić <YOUR_CONNECTION_STRING> wartość parametrów połączeń ustawioną na bok w edytorze tekstów.

  2. Użyj narzędzia npm, aby zainstalować lub zaktualizować interfejs wiersza polecenia usługi Static Web Apps. Wybierz, które polecenie jest najlepsze dla Twojej sytuacji.

    Aby przeprowadzić instalację, użyj polecenia npm install.

    npm install -g @azure/static-web-apps-cli

    Aby zaktualizować, użyj polecenia npm update.

    npm update

  3. Użyj polecenia , swa db init aby wygenerować plik konfiguracji bazy danych.

    swa db init --database-type cosmosdb_nosql --cosmosdb_nosql-database MyTestPersonDatabase

    Polecenie init tworzy plik staticwebapp.database.config.json w folderze swa-db-connections.

  4. Wklej ten przykładowy schemat do wygenerowanego pliku staticwebapp.database.schema.gql .

    Ponieważ usługa Cosmos DB for NoSQL jest niezależną bazą danych schematu, połączenia bazy danych usługi Azure Static Web Apps nie mogą wyodrębnić schematu bazy danych. Plik staticwebapp.database.schema.gql umożliwia określenie schematu bazy danych Cosmos DB for NoSQL dla usługi Static Web Apps.

    type Person @model {
  id: ID
  Name: String
}

  5. Wklej tę przykładową konfigurację do pliku staticwebapp.database.config.json wygenerowany. Zwróć uwagę, że usługa Cosmos DB for NoSQL ma więcej opcji w data-source obiekcie wskazujących bazę danych Cosmos DB i plik schematu wymagany do nawiązania połączeń z bazą danych w celu zrozumienia schematu bazy danych.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "MyTestPersonDatabase",
      "schema": "staticwebapp.database.schema.gql"
    },
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "mode": "production",
      "cors": {
        "origins": ["http://localhost:4280"],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      }
    }
  },
  "entities": {
    "Person": {
      "source": "MyTestPersonContainer",
      "permissions": [
        {
          "actions": ["*"],
          "role": "anonymous"
        }
      ]
    }
  }
}

Przed przejściem do następnego kroku zapoznaj się z poniższą tabelą, która wyjaśnia różne aspekty pliku konfiguracji. Aby uzyskać pełną dokumentację dotyczącą pliku konfiguracji i funkcji, takich jak relacje i zasady dotyczące zabezpieczeń na poziomie elementu, zapoznaj się z dokumentacją narzędzia Data API Builder.

Funkcja Wyjaśnienie
Połączenie z bazą danych Podczas programowania środowisko uruchomieniowe odczytuje parametry połączenia z wartości parametry połączenia w pliku konfiguracji. Chociaż można określić parametry połączenia bezpośrednio w pliku konfiguracji, najlepszym rozwiązaniem jest przechowywanie parametry połączenia w lokalnej zmiennej środowiskowej. Możesz odwołać się do wartości zmiennych środowiskowych w pliku konfiguracji za pośrednictwem @env('DATABASE_CONNECTION_STRING') notacji. Wartość parametry połączenia zostaje zastąpiona przez usługę Static Web Apps dla wdrożonej witryny z informacjami zebranymi podczas łączenia bazy danych.
Punkt końcowy interfejsu API Punkt końcowy graphQL jest dostępny za pośrednictwem /data-api/graphql zgodnie z konfiguracją w tym pliku konfiguracji. Możesz skonfigurować ścieżkę GraphQL, ale /data-api prefiks nie jest konfigurowalny.
Zabezpieczenia interfejsu API Ustawienia runtime.host.cors umożliwiają zdefiniowanie dozwolonych źródeł, które mogą wysyłać żądania do interfejsu API. W takim przypadku konfiguracja odzwierciedla środowisko deweloperskie i zezwala na http://localhost:4280 listę lokalizacji.
Model jednostki Definiuje jednostki uwidocznione za pośrednictwem tras jako typy w schemacie GraphQL. W takim przypadku nazwa Person jest nazwą uwidacznianą dla punktu końcowego, podczas gdy entities.<NAME>.source jest to schemat bazy danych i mapowanie tabeli. Zwróć uwagę, że nazwa punktu końcowego interfejsu API nie musi być identyczna z nazwą tabeli.
Zabezpieczenia jednostek Reguły uprawnień wymienione w tablicy entity.<NAME>.permissions kontrolują ustawienia autoryzacji dla jednostki. Jednostkę można zabezpieczyć przy użyciu ról w taki sam sposób, jak zabezpieczanie tras za pomocą ról.

Uwaga

Plik connection-stringkonfiguracji , host.modei graphql.allow-introspection właściwości są zastępowane podczas wdrażania lokacji. Twój parametry połączenia zostanie zastąpiony szczegółami uwierzytelniania zebranymi podczas łączenia bazy danych z zasobem usługi Static Web Apps. Właściwość jest ustawiona host.mode na production, a właściwość jest ustawiona graphql.allow-introspection na false. Te przesłonięcia zapewniają spójność plików konfiguracji w obciążeniach programistycznych i produkcyjnych, zapewniając jednocześnie, że zasób usługi Static Web Apps z włączonymi połączeniami bazy danych jest bezpieczny i gotowy do produkcji.

Za pomocą statycznej aplikacji internetowej skonfigurowanej do nawiązywania połączenia z bazą danych możesz teraz zweryfikować połączenie.

Aktualizowanie strony głównej

Zastąp znaczniki między tagami body w pliku index.html następującym kodem HTML.

<h1>Static Web Apps Database Connections</h1>
<blockquote>
    Open the console in the browser developer tools to see the API responses.
</blockquote>
<div>
    <button id="list" onclick="list()">List</button>
    <button id="get" onclick="get()">Get</button>
    <button id="update" onclick="update()">Update</button>
    <button id="create" onclick="create()">Create</button>
    <button id="delete" onclick="del()">Delete</button>
</div>
<script>
    // add JavaScript here
</script>

Lokalne uruchamianie aplikacji

Teraz możesz uruchomić witrynę internetową i bezpośrednio manipulować danymi w bazie danych.

Ważne

Aby zwiększyć bezpieczeństwo wdrożeń z interfejsu wiersza polecenia usługi Static Web Apps, wprowadzono zmianę powodującą niezgodność, która wymaga uaktualnienia do najnowszej wersji (2.0.2) interfejsu wiersza polecenia usługi Static Web Apps do 15 stycznia 2025 r.

  1. Użyj narzędzia npm, aby zainstalować lub zaktualizować interfejs wiersza polecenia usługi Static Web Apps. Wybierz, które polecenie jest najlepsze dla Twojej sytuacji.

    Aby przeprowadzić instalację, użyj polecenia npm install.

    npm install -g @azure/static-web-apps-cli

    Aby zaktualizować, użyj polecenia npm update.

    npm update

  2. Uruchom statyczną aplikację internetową przy użyciu konfiguracji bazy danych.

    swa start ./src --data-api-location swa-db-connections

Po uruchomieniu interfejsu wiersza polecenia możesz uzyskać dostęp do bazy danych za pośrednictwem punktów końcowych zgodnie z definicją w pliku staticwebapp.database.config.json .

Punkt http://localhost:4280/data-api/graphql końcowy akceptuje zapytania GraphQL i mutacje.

Manipulowanie danymi

Poniższe polecenia niezależne od platformy pokazują, jak wykonywać pełne operacje CRUD w bazie danych.

Dane wyjściowe każdej funkcji są wyświetlane w oknie konsoli przeglądarki.

Otwórz narzędzia deweloperskie, naciskając CMD/CTRL + SHIFT + I i wybierz kartę Konsola.

Wyświetl wszystkie elementy

Dodaj następujący kod między tagami script w index.html.

async function list() {

  const query = `
      {
        people {
          items {
            id
            Name
          }
        }
      }`;
      
  const endpoint = "/data-api/graphql";
  const response = await fetch(endpoint, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query: query })
  });
  const result = await response.json();
  console.table(result.data.people.items);
}

W tym przykładzie:

  • Zapytanie GraphQL wybiera Id pola i Name z bazy danych.
  • Żądanie przekazane do serwera wymaga ładunku, w którym query właściwość przechowuje definicję zapytania.
  • Dane w ładunku odpowiedzi znajdują się we data.people.items właściwości .

Odśwież stronę i wybierz przycisk Lista .

W oknie konsoli przeglądarki zostanie wyświetlona tabela zawierająca wszystkie rekordy w bazie danych.

identyfikator Nazwisko
1 Słoneczny
2 Dheeraj

Oto zrzut ekranu przedstawiający wygląd w przeglądarce.

Przeglądarka sieci Web przedstawiająca wyniki wyboru bazy danych w oknie konsoli narzędzi deweloperskich.

Pobierz według identyfikatora

Dodaj następujący kod między tagami script w index.html.

async function get() {

  const id = '1';

  const gql = `
    query getById($id: ID!) {
      person_by_pk(id: $id) {
        id
        Name
      }
    }`;

  const query = {
    query: gql,
    variables: {
      id: id,
    },
  };

  const endpoint = "/data-api/graphql";
  const response = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query),
  });
  const result = await response.json();
  console.table(result.data.person_by_pk);
}

W tym przykładzie:

  • Zapytanie GraphQL wybiera id pola i Name z bazy danych.
  • Żądanie przekazane do serwera wymaga ładunku, w którym query właściwość przechowuje definicję zapytania.
  • Dane w ładunku odpowiedzi znajdują się we data.person_by_pk właściwości .

Odśwież stronę i wybierz przycisk Pobierz .

W oknie konsoli przeglądarki zostanie wyświetlona tabela zawierająca pojedynczy rekord żądany z bazy danych.

identyfikator Nazwisko
1 Słoneczny

Zaktualizuj

Dodaj następujący kod między tagami script w index.html.

async function update() {

  const id = '1';
  const data = {
    id: id,
    Name: "Molly"
  };

  const gql = `
    mutation update($id: ID!, $_partitionKeyValue: String!, $item: UpdatePersonInput!) {
      updatePerson(id: $id, _partitionKeyValue: $_partitionKeyValue, item: $item) {
        id
        Name
      }
    }`;

  const query = {
    query: gql,
    variables: {
      id: id,
      _partitionKeyValue: id,
      item: data
    } 
  };

  const endpoint = "/data-api/graphql";
  const res = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query)
  });

  const result = await res.json();
  console.table(result.data.updatePerson);
}

W tym przykładzie:

  • Zapytanie GraphQL wybiera id pola i Name z bazy danych.
  • Obiekt query zawiera zapytanie GraphQL we query właściwości .
  • Wartości argumentów funkcji GraphQL są przekazywane za pośrednictwem query.variables właściwości .
  • Żądanie przekazane do serwera wymaga ładunku, w którym query właściwość przechowuje definicję zapytania.
  • Dane w ładunku odpowiedzi znajdują się we data.updatePerson właściwości .

Odśwież stronę i wybierz przycisk Aktualizuj .

W oknie konsoli przeglądarki zostanie wyświetlona tabela przedstawiająca zaktualizowane dane.

identyfikator Nazwisko
1 Molly

Utworzenie

Dodaj następujący kod między tagami script w index.html.

async function create() {

  const data = {
    id: "3",
    Name: "Pedro"
  };

  const gql = `
    mutation create($item: CreatePersonInput!) {
      createPerson(item: $item) {
        id
        Name
      }
    }`;
  
  const query = {
    query: gql,
    variables: {
      item: data
    } 
  };
  
  const endpoint = "/data-api/graphql";
  const result = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query)
  });

  const response = await result.json();
  console.table(response.data.createPerson);
}

W tym przykładzie:

  • Zapytanie GraphQL wybiera id pola i Name z bazy danych.
  • Obiekt query zawiera zapytanie GraphQL we query właściwości .
  • Wartości argumentów funkcji GraphQL są przekazywane za pośrednictwem query.variables właściwości .
  • Żądanie przekazane do serwera wymaga ładunku, w którym query właściwość przechowuje definicję zapytania.
  • Dane w ładunku odpowiedzi znajdują się we data.updatePerson właściwości .

Odśwież stronę i wybierz przycisk Utwórz .

W oknie konsoli przeglądarki zostanie wyświetlona tabela przedstawiająca nowy rekord w bazie danych.

identyfikator Nazwisko
3 Pedro

Delete

Dodaj następujący kod między tagami script w index.html.

async function del() {

  const id = '3';

  const gql = `
    mutation del($id: ID!, $_partitionKeyValue: String!) {
      deletePerson(id: $id, _partitionKeyValue: $_partitionKeyValue) {
        id
      }
    }`;

  const query = {
    query: gql,
    variables: {
      id: id,
    _partitionKeyValue: id
    }
  };

  const endpoint = "/data-api/graphql";
  const response = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query)
  });

  const result = await response.json();
  console.log(`Record deleted: ${ JSON.stringify(result.data) }`);
}

W tym przykładzie:

  • Zapytanie GraphQL wybiera Id pole z bazy danych.
  • Obiekt query zawiera zapytanie GraphQL we query właściwości .
  • Wartości argumentów funkcji GraphQL są przekazywane za pośrednictwem query.variables właściwości .
  • Żądanie przekazane do serwera wymaga ładunku, w którym query właściwość przechowuje definicję zapytania.
  • Dane w ładunku odpowiedzi znajdują się we data.deletePerson właściwości .

Odśwież stronę i wybierz przycisk Usuń .

W oknie konsoli przeglądarki zostanie wyświetlona tabela przedstawiająca odpowiedź z żądania usunięcia.

Rekord usunięty: 2

Teraz, gdy pracujesz z witryną lokalnie, możesz teraz wdrożyć ją na platformie Azure.

Wdrażanie witryny

Aby wdrożyć tę lokację w środowisku produkcyjnym, wystarczy zatwierdzić plik konfiguracji i wypchnąć zmiany na serwer.

  1. Zatwierdź zmiany konfiguracji.

    git commit -am "Add database configuration"

  2. Wypchnij zmiany na serwer.

    git push origin main

  3. Poczekaj na skompilowanie aplikacji internetowej.

  4. Przejdź do statycznej aplikacji internetowej w przeglądarce.

  5. Wybierz przycisk Lista, aby wyświetlić listę wszystkich elementów.

    Dane wyjściowe powinny przypominać to, co pokazano na tym zrzucie ekranu.

    Przeglądarka sieci Web przedstawiająca wyniki z listy rekordów z bazy danych w oknie konsoli narzędzi deweloperskich.

Łączenie bazy danych ze statyczną aplikacją internetową

Wykonaj poniższe kroki, aby utworzyć połączenie między wystąpieniem usługi Static Web Apps witryny a bazą danych.

  1. Otwórz statyczną aplikację internetową w witrynie Azure Portal.

  2. W sekcji Ustawienia wybierz pozycję Połączenie z bazą danych.

  3. W sekcji Produkcja wybierz link Połącz istniejącą bazę danych.

  4. W oknie Połącz istniejącą bazę danych wprowadź następujące wartości:

    Właściwości Wartość
    Typ bazy danych Wybierz typ bazy danych z listy rozwijanej.
    Subskrypcja Wybierz subskrypcję platformy Azure z listy rozwijanej.
    Nazwa bazy danych Wybierz nazwę bazy danych, którą chcesz połączyć ze statyczną aplikacją internetową.
    Typ uwierzytelniania Wybierz pozycję Parametry połączenia.

  5. Wybierz przycisk OK.

Sprawdź, czy baza danych jest połączona z zasobem usługi Static Web Apps

Po połączeniu bazy danych ze statyczną aplikacją internetową i zakończeniu tworzenia witryny wykonaj następujące kroki, aby zweryfikować połączenie z bazą danych.

  1. Otwórz statyczną aplikację internetową w witrynie Azure Portal.

  2. W sekcji Podstawy wybierz adres URL zasobu usługi Static Web Apps, aby przejść do statycznej aplikacji internetowej.

  3. Wybierz przycisk Lista, aby wyświetlić listę wszystkich elementów.

    Dane wyjściowe powinny przypominać to, co pokazano na tym zrzucie ekranu.

    Przeglądarka sieci Web przedstawiająca wyniki z listy rekordów z bazy danych w oknie konsoli narzędzi deweloperskich.

Czyszczenie zasobów

Jeśli chcesz usunąć zasoby utworzone podczas tego samouczka, musisz odłączyć bazę danych i usunąć przykładowe dane.

  1. Odłącz bazę danych: otwórz statyczną aplikację internetową w witrynie Azure Portal. W sekcji Ustawienia wybierz pozycję Połączenie z bazą danych. Obok połączonej bazy danych wybierz pozycję Wyświetl szczegóły. W oknie Szczegóły połączenia z bazą danych wybierz przycisk Odłącz.

  2. Usuń przykładowe dane: w bazie danych usuń tabelę o nazwie MyTestPersonContainer.

Następne kroki

Dodawanie interfejsu API