Bagikan melalui

Tutorial: Menambahkan koneksi database Azure Cosmos DB di Azure Static Web Apps (pratinjau)

Dalam tutorial ini, Anda mempelajari cara menyambungkan Azure Cosmos DB untuk database NoSQL ke aplikasi web statis Anda. Setelah dikonfigurasi /data-api , Anda dapat membuat permintaan GraphQL ke titik akhir bawaan untuk memanipulasi data tanpa harus menulis kode backend.

Demi kesederhanaan, tutorial ini menunjukkan kepada Anda cara menggunakan database Azure untuk tujuan pengembangan lokal, tetapi Anda juga dapat menggunakan server database lokal untuk kebutuhan pengembangan lokal Anda.

Catatan

Tutorial ini menunjukkan cara menggunakan Azure Cosmos DB untuk NoSQL. Jika Anda ingin menggunakan database lain, lihat tutorial Azure SQL, MySQL, atau PostgreSQL .

Browser web menampilkan hasil dari Cosmos DB di jendela konsol alat pengembang.

Dalam tutorial ini, Anda mempelajari caranya:

  • Menautkan Azure Cosmos DB untuk database NoSQL ke aplikasi web statis Anda
  • Membuat, membaca, memperbarui, dan menghapus data

Prasyarat

Untuk menyelesaikan tutorial ini, Anda harus memiliki Azure Cosmos DB untuk database NoSQL dan aplikasi web statis yang ada.

Sumber daya Deskripsi
Azure Cosmos DB untuk NoSQL Database Jika Anda belum memilikinya, ikuti langkah-langkah dalam panduan Membuat database Azure Cosmos DB.
Aplikasi web statis yang ada Jika Anda belum memilikinya, ikuti langkah-langkah dalam panduan memulai untuk membuat aplikasi web statis Tanpa Kerangka Kerja .

Mulailah dengan mengonfigurasi database Anda untuk bekerja dengan fitur koneksi database Azure Static Web Apps.

Mengonfigurasi konektivitas database

Azure Static Web Apps harus memiliki akses jaringan ke database Anda agar koneksi database berfungsi. Selain itu, untuk menggunakan database Azure untuk pengembangan lokal, Anda perlu mengonfigurasi database Anda untuk mengizinkan permintaan dari alamat IP Anda sendiri.

  1. Buka akun Azure Cosmos DB for NoSQL Anda di portal Azure.

  2. Di bawah bagian Pengaturan, pilih Jaringan.

  3. Di bawah bagian Akses publik, pilih Semua jaringan. Tindakan ini memungkinkan Anda menggunakan database cloud untuk pengembangan lokal, bahwa sumber daya Static Web Apps yang Anda sebarkan dapat mengakses database Anda, dan Anda dapat mengkueri database Anda dari portal.

  4. Pilih Simpan.

Mendapatkan string koneksi database untuk pengembangan lokal

Untuk menggunakan database Azure Anda untuk pengembangan lokal, Anda perlu mengambil string koneksi database Anda. Anda dapat melewati langkah ini jika Anda berencana menggunakan database lokal untuk tujuan pengembangan.

  1. Buka akun Azure Cosmos DB for NoSQL Anda di portal Azure.

  2. Di bawah bagian Pengaturan , pilih Kunci.

  3. Dari kotak STRING KONEKSI UTAMA, salin string koneksi dan sisihkan di editor teks.

Membuat data sampel

Buat tabel sampel dan seed dengan data sampel agar sesuai dengan tutorial.

  1. Di jendela navigasi sebelah kiri, pilih Data Explorer.

  2. Pilih New Container. Masukkan ID Database sebagai Create new, dan masukkan MyTestPersonDatabase sebagai nilai.

  3. Masukkan ID Kontainer dari MyTestPersonContainer.

  4. Masukkan kunci id partisi (nilai ini diawali dengan /).

  5. Pilih OK.

  6. Pilih kontainer MyTestPersonContainer .

  7. Pilih Itemnya.

  8. Pilih Item Baru dan masukkan nilai berikut:

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

Mengonfigurasi aplikasi web statis

Sisa tutorial ini berfokus pada pengeditan kode sumber aplikasi web statis Anda untuk menggunakan koneksi database secara lokal.

Penting

Langkah-langkah berikut mengasumsikan Anda bekerja dengan aplikasi web statis yang dibuat dalam panduan memulai. Jika Anda menggunakan proyek yang berbeda, pastikan untuk menyesuaikan perintah git berikut agar sesuai dengan nama cabang Anda.

  1. Beralih ke cabang main.

    git checkout main

  2. Sinkronkan versi lokal Anda dengan apa yang ada di GitHub dengan menggunakan git pull.

    git pull origin main

Membuat file konfigurasi database

Selanjutnya, buat file konfigurasi yang digunakan aplikasi web statis Anda untuk berinteraksi dengan database.

  1. Buka terminal Anda dan buat variabel baru untuk menahan string koneksi Anda. Sintaksis tertentu dapat bervariasi tergantung pada jenis shell yang Anda gunakan.

    export DATABASE_CONNECTION_STRING='<YOUR_CONNECTION_STRING>'

    Pastikan untuk mengganti <YOUR_CONNECTION_STRING> dengan nilai string koneksi yang Anda sisihkan di editor teks.

  2. Gunakan npm untuk menginstal atau memperbarui CLI Static Web Apps. Pilih perintah mana yang terbaik untuk situasi Anda.

    Untuk menginstal, gunakan npm install.

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

    Untuk memperbarui, gunakan npm update.

    npm update

  3. swa db init Gunakan perintah untuk menghasilkan file konfigurasi database.

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

    Perintah init membuat file staticwebapp.database.config.json di folder swa-db-connections .

  4. Tempelkan skema sampel ini ke dalam file staticwebapp.database.schema.gql yang Anda buat.

    Karena Cosmos DB for NoSQL adalah database agnostik skema, koneksi database Azure Static Web Apps tidak dapat mengekstrak skema database Anda. File staticwebapp.database.schema.gql memungkinkan Anda menentukan skema database Cosmos DB for NoSQL untuk Static Web Apps.

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

  5. Tempelkan konfigurasi sampel ini ke dalam file staticwebapp.database.config.json Anda buat. Perhatikan bahwa Cosmos DB for NoSQL memiliki lebih banyak opsi dalam data-source objek untuk menunjukkan database Cosmos DB dan file skema yang diperlukan untuk koneksi database untuk memahami skema database.

{
  "$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"
        }
      ]
    }
  }
}

Sebelum melanjutkan ke langkah berikutnya, tinjau tabel berikut yang menjelaskan berbagai aspek file konfigurasi. Untuk dokumentasi lengkap tentang file konfigurasi dan fungsionalitas seperti hubungan dan kebijakan untuk keamanan tingkat item, lihat dokumentasi Data API Builder.

Fitur Penjelasan
Koneksi database Dalam pengembangan, runtime membaca string koneksi dari nilai string koneksi dalam file konfigurasi. Meskipun Anda dapat menentukan string koneksi langsung dalam file konfigurasi, praktik terbaiknya adalah menyimpan string koneksi dalam variabel lingkungan lokal. Anda dapat merujuk ke nilai variabel lingkungan dalam file konfigurasi melalui @env('DATABASE_CONNECTION_STRING') notasi. Nilai string koneksi ditimpa oleh Static Web Apps untuk situs yang disebarkan dengan informasi yang dikumpulkan saat Anda menyambungkan database Anda.
Titik akhir API Titik akhir GraphQL tersedia melalui /data-api/graphql seperti yang dikonfigurasi dalam file konfigurasi ini. Anda dapat mengonfigurasi jalur GraphQL, tetapi awalan /data-api tidak dapat dikonfigurasi.
Keamanan API Pengaturan memungkinkan runtime.host.cors Anda menentukan asal yang diizinkan yang dapat membuat permintaan ke API. Dalam hal ini, konfigurasi mencerminkan lingkungan pengembangan dan mengizinkan http://localhost:4280 daftar lokasi.
Model entitas Menentukan entitas yang diekspos melalui rute sebagai jenis dalam skema GraphQL. Dalam hal ini, nama Orang, adalah nama yang diekspos ke titik akhir sementara entities.<NAME>.source adalah skema database dan pemetaan tabel. Perhatikan bagaimana nama titik akhir API tidak perlu identik dengan nama tabel.
Keamanan entitas Aturan izin yang tercantum dalam entity.<NAME>.permissions array mengontrol pengaturan otorisasi untuk entitas. Anda dapat mengamankan entitas dengan peran dengan cara yang sama seperti Anda mengamankan rute dengan peran.

Catatan

Properti , , host.modedan graphql.allow-introspection file connection-stringkonfigurasi ditimpa saat Anda menyebarkan situs Anda. string koneksi Anda ditimpa dengan detail autentikasi yang dikumpulkan saat Anda menyambungkan database ke sumber daya Static Web Apps Anda. Properti host.mode diatur ke production, dan graphql.allow-introspection diatur ke false. Penimpaan ini memberikan konsistensi dalam file konfigurasi Anda di seluruh beban kerja pengembangan dan produksi Anda, sekaligus memastikan sumber daya Static Web Apps Anda dengan koneksi database yang diaktifkan aman dan siap produksi.

Dengan aplikasi web statis yang dikonfigurasi untuk menyambungkan ke database, Anda sekarang dapat memverifikasi koneksi.

Perbarui beranda

Ganti markup antara body tag dalam file index.html dengan HTML berikut.

<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>

Memulai aplikasi secara lokal

Sekarang Anda dapat menjalankan situs web Anda dan memanipulasi data dalam database secara langsung.

Penting

Untuk meningkatkan keamanan penyebaran dari CLI Static Web Apps, perubahan yang melanggar diperkenalkan yang mengharuskan Anda untuk meningkatkan ke versi terbaru (2.0.2) dari CLI Static Web Apps pada 15 Jan 2025.

  1. Gunakan npm untuk menginstal atau memperbarui CLI Static Web Apps. Pilih perintah mana yang terbaik untuk situasi Anda.

    Untuk menginstal, gunakan npm install.

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

    Untuk memperbarui, gunakan npm update.

    npm update

  2. Mulai aplikasi web statis dengan konfigurasi database.

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

Sekarang setelah CLI dimulai, Anda dapat mengakses database Anda melalui titik akhir seperti yang ditentukan dalam file staticwebapp.database.config.json .

Titik http://localhost:4280/data-api/graphql akhir menerima kueri dan mutasi GraphQL.

Memanipulasi data

Perintah framework-agnostic berikut menunjukkan cara melakukan operasi CRUD penuh pada database Anda.

Output untuk setiap fungsi muncul di jendela konsol browser.

Buka alat pengembang dengan menekan CMD/CTRL + SHIFT + I dan pilih tab Konsol.

Mencantumkan semua item

Tambahkan kode berikut di antara script tag di 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);
}

Dalam contoh ini:

  • Kueri GraphQL memilih Id bidang dan Name dari database.
  • Permintaan yang diteruskan ke server memerlukan payload di mana query properti menyimpan definisi kueri.
  • Data dalam payload respons ditemukan di data.people.items properti .

Refresh halaman dan pilih tombol Daftar .

Jendela konsol browser sekarang menampilkan tabel yang mencantumkan semua rekaman dalam database.

id Nama
1 Cerah
2 Dheeraj

Berikut adalah cuplikan layar tampilannya di browser Anda.

Browser web memperlihatkan hasil dari pilihan database di jendela konsol alat pengembang.

Dapatkan berdasarkan ID

Tambahkan kode berikut di antara script tag di 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);
}

Dalam contoh ini:

  • Kueri GraphQL memilih id bidang dan Name dari database.
  • Permintaan yang diteruskan ke server memerlukan payload di mana query properti menyimpan definisi kueri.
  • Data dalam payload respons ditemukan di data.person_by_pk properti .

Refresh halaman dan pilih tombol Dapatkan .

Jendela konsol browser sekarang menampilkan tabel yang mencantumkan satu rekaman yang diminta dari database.

id Nama
1 Cerah

Pembaruan

Tambahkan kode berikut di antara script tag di 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);
}

Dalam contoh ini:

  • Kueri GraphQL memilih id bidang dan Name dari database.
  • Objek query menyimpan kueri GraphQL di query properti .
  • Nilai argumen ke fungsi GraphQL diteruskan melalui query.variables properti .
  • Permintaan yang diteruskan ke server memerlukan payload di mana query properti menyimpan definisi kueri.
  • Data dalam payload respons ditemukan di data.updatePerson properti .

Refresh halaman dan pilih tombol Perbarui .

Jendela konsol browser sekarang menampilkan tabel yang menampilkan data yang diperbarui.

id Nama
1 Molly

Buat

Tambahkan kode berikut di antara script tag di 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);
}

Dalam contoh ini:

  • Kueri GraphQL memilih id bidang dan Name dari database.
  • Objek query menyimpan kueri GraphQL di query properti .
  • Nilai argumen ke fungsi GraphQL diteruskan melalui query.variables properti .
  • Permintaan yang diteruskan ke server memerlukan payload di mana query properti menyimpan definisi kueri.
  • Data dalam payload respons ditemukan di data.updatePerson properti .

Refresh halaman dan pilih tombol Buat .

Jendela konsol browser sekarang menampilkan tabel yang menampilkan rekaman baru dalam database.

id Nama
3 Pedro

Hapus

Tambahkan kode berikut di antara script tag di 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) }`);
}

Dalam contoh ini:

  • Kueri GraphQL memilih Id bidang dari database.
  • Objek query menyimpan kueri GraphQL di query properti .
  • Nilai argumen ke fungsi GraphQL diteruskan melalui query.variables properti .
  • Permintaan yang diteruskan ke server memerlukan payload di mana query properti menyimpan definisi kueri.
  • Data dalam payload respons ditemukan di data.deletePerson properti .

Refresh halaman dan pilih tombol Hapus .

Jendela konsol browser sekarang menampilkan tabel yang menampilkan respons dari permintaan penghapusan.

Rekaman dihapus: 2

Sekarang setelah Anda bekerja dengan situs Anda secara lokal, Anda sekarang dapat menyebarkannya ke Azure.

Menyebarkan situs Anda

Untuk menyebarkan situs ini ke produksi, Anda hanya perlu menerapkan file konfigurasi dan mendorong perubahan Anda ke server.

  1. Terapkan perubahan konfigurasi.

    git commit -am "Add database configuration"

  2. Dorong perubahan Anda ke server.

    git push origin main

  3. Tunggu hingga aplikasi web Anda dibuat.

  4. Buka aplikasi web statis Anda di browser.

  5. Pilih tombol Daftar untuk mencantumkan semua item.

    Output harus menyerupai apa yang ditunjukkan dalam cuplikan layar ini.

    Browser web memperlihatkan hasil dari mencantumkan rekaman dari database di jendela konsol alat pengembang.

Menyambungkan database ke aplikasi web statis Anda

Gunakan langkah-langkah berikut untuk membuat koneksi antara instans Static Web Apps situs Anda dan database Anda.

  1. Buka aplikasi web statis Anda di portal Azure.

  2. Di bagian Pengaturan , pilih Koneksi database.

  3. Di bawah bagian Produksi, pilih tautan Tautkan database yang sudah ada.

  4. Di jendela Tautkan database yang sudah ada, masukkan nilai berikut ini:

    Properti Nilai
    Jenis Database Pilih jenis database Anda dari daftar dropdown.
    Langganan Pilih langganan Azure Anda dari daftar dropdown.
    Nama Database Pilih nama database yang ingin Anda tautkan ke aplikasi web statis Anda.
    Jenis Autentikasi Pilih String koneksi.

  5. Pilih OK.

Verifikasi bahwa database Anda tersambung ke sumber daya Static Web Apps Anda

Setelah Anda menyambungkan database ke aplikasi web statis dan situs selesai dibangun, gunakan langkah-langkah berikut untuk memverifikasi koneksi database.

  1. Buka aplikasi web statis Anda di portal Azure.

  2. Di bagian Esensial , pilih URL sumber daya Static Web Apps Anda untuk menavigasi ke aplikasi web statis Anda.

  3. Pilih tombol Daftar untuk mencantumkan semua item.

    Output harus menyerupai apa yang ditunjukkan dalam cuplikan layar ini.

    Browser web memperlihatkan hasil dari mencantumkan rekaman dari database di jendela konsol alat pengembang.

Membersihkan sumber daya

Jika Anda ingin menghapus sumber daya yang dibuat selama tutorial ini, Anda perlu membatalkan tautan database dan menghapus data sampel.

  1. Batalkan tautan database: Buka aplikasi web statis Anda di portal Azure. Di bawah bagian Pengaturan, pilih Koneksi database. Di samping database tertaut, pilih Tampilkan detail. Di jendela Detail koneksi database, pilih tombol Batalkan tautan .

  2. Menghapus data sampel: Di database Anda, hapus tabel bernama MyTestPersonContainer.

Langkah berikutnya

Menambahkan API