Öğretici: Azure Static Web Apps'te Azure Cosmos DB veritabanı bağlantısı ekleme (önizleme)

Bu öğreticide, NoSQL için Azure Cosmos DB veritabanını statik web uygulamanıza bağlamayı öğreneceksiniz. Yapılandırıldıktan sonra arka uç kodu yazmak zorunda kalmadan verileri işlemek için yerleşik /data-api uç noktaya GraphQL isteklerinde bulunabilirsiniz.

Kolaylık olması açısından bu öğreticide yerel geliştirme amacıyla Azure veritabanının nasıl kullanılacağı gösterilmektedir, ancak yerel geliştirme gereksinimleriniz için yerel bir veritabanı sunucusu da kullanabilirsiniz.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

Önkoşullar

Bu öğreticiyi tamamlamak için mevcut bir NoSQL için Azure Cosmos DB veritabanınız ve statik web uygulamanız olması gerekir.

Veritabanınızı Azure Static Web Apps veritabanı bağlantı özelliğiyle çalışacak şekilde yapılandırarak başlayın.

Veritabanı bağlantısını yapılandırma

Veritabanı bağlantılarının çalışması için Azure Static Web Apps'in veritabanınıza ağ erişimi olmalıdır. Ayrıca, yerel geliştirme için bir Azure veritabanı kullanmak için veritabanınızı kendi IP adresinizden gelen isteklere izin verecek şekilde yapılandırmanız gerekir.

1. Azure portalında NoSQL için Azure Cosmos DB hesabınıza gidin.

2. Ayarlar bölümünün altında, Ağ seçeneğini belirleyin.

3. Genel erişim bölümünde Tüm ağlar'ı seçin. Bu eylem, yerel geliştirme için bulut veritabanını kullanmanıza, dağıtılan Statik Web Apps kaynağınızın veritabanınıza erişmesine ve veritabanınızı portaldan sorgulamanıza olanak tanır.

4. Kaydet'i seçin.

Yerel geliştirme için veritabanı bağlantı dizesi alma

Yerel geliştirme için Azure veritabanınızı kullanmak için veritabanınızın bağlantı dizesi almanız gerekir. Geliştirme amacıyla yerel veritabanı kullanmayı planlıyorsanız bu adımı atlayabilirsiniz.

1. Azure portalında NoSQL için Azure Cosmos DB hesabınıza gidin.

2. Ayarlar bölümünde Anahtarlar'ı seçin.

3. BİRİnCİl BAĞLANTI DIZESİ kutusundan bağlantı dizesi kopyalayın ve bir metin düzenleyicisinde bir kenara bırakın.

Örnek veri oluşturma

Örnek bir tablo oluşturun ve öğreticiyle eşleşecek örnek verilerle bu tabloyu dağıtın.

1. Sol gezinti penceresinde Veri Gezgini'ı seçin.

2. Yeni Kapsayıcı'ya tıklayın. Veritabanı Kimliğini olarak Create newgirin ve değer olarak girin MyTestPersonDatabase .

3. kapsayıcı kimliğini MyTestPersonContainergirin.

4. bir bölüm anahtarı id girin (bu değer ile ön eklenmiştir /).

5. Tamam'ı seçin.

6. MyTestPersonContainer kapsayıcısını seçin.

7. Öğelerini seçin.

8. Yeni Öğe'yi seçin ve aşağıdaki değeri girin:

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

Statik web uygulamasını yapılandırma

Bu öğreticinin geri kalanı, veritabanı bağlantılarını yerel olarak kullanmak için statik web uygulamanızın kaynak kodunu düzenlemeye odaklanır.

1. Dala main geçin.

   git checkout main
   

2. kullanarak git pullyerel sürümünüzü GitHub'da bulunanlarla eşitleyin.

   git pull origin main
   

Veritabanı yapılandırma dosyasını oluşturma

Ardından, statik web uygulamanızın veritabanıyla arabirim oluşturmak için kullandığı yapılandırma dosyasını oluşturun.

1. Terminalinizi açın ve bağlantı dizesi tutmak için yeni bir değişken oluşturun. Söz dizimi, kullandığınız kabuk türüne bağlı olarak değişebilir.

   • Bash
   • PowerShell

   export DATABASE_CONNECTION_STRING='<YOUR_CONNECTION_STRING>'
   

   değerini bir metin düzenleyicisinde ayırdığınız bağlantı dizesi değeriyle değiştirdiğinizden <YOUR_CONNECTION_STRING> emin olun.

2. Statik Web Uygulamaları CLI'sını yüklemek veya güncelleştirmek için npm kullanın. Durumunuz için en uygun komutu seçin.

   Yüklemek için kullanın npm install.

   • Bash
   • PowerShell

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

   Güncelleştirmek için kullanın npm update.

   • Bash
   • PowerShell

   npm update
   

3. swa db init Veritabanı yapılandırma dosyası oluşturmak için komutunu kullanın.

   • Bash
   • PowerShell

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

   init komutu swa-db-connections klasöründe staticwebapp.database.config.json dosyasını oluşturur.

4. Bu örnek şemayı oluşturduğunuz staticwebapp.database.schema.gql dosyasına yapıştırın.

   NoSQL için Cosmos DB şemadan bağımsız bir veritabanı olduğundan Azure Static Web Apps veritabanı bağlantıları veritabanınızın şemasını ayıklayamaz. staticwebapp.database.schema.gql dosyası, Static Web Apps için NoSQL için Cosmos DB veritabanınızın şemasını belirtmenize olanak tanır.

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

5. Bu örnek yapılandırmayı oluşturduğunuz staticwebapp.database.config.json dosyaya yapıştırın. NoSQL için Cosmos DB'nin nesnesinde data-source Cosmos DB veritabanını ve veritabanı bağlantılarının veritabanının şemasını anlaması için gereken şema dosyasını gösteren daha fazla seçenek olduğuna dikkat edin.

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

Sonraki adıma geçmeden önce, yapılandırma dosyasının farklı yönlerini açıklayan aşağıdaki tabloyu gözden geçirin. Yapılandırma dosyası ve öğe düzeyinde güvenlik için ilişkiler ve ilkeler gibi işlevlerle ilgili tam belgeler için Data API Builder belgelerine bakın.

Statik web uygulaması veritabanına bağlanacak şekilde yapılandırıldığında bağlantıyı doğrulayabilirsiniz.

Giriş sayfasını güncelleştirme

index.html dosyasındaki body etiketler arasındaki işaretlemeyi aşağıdaki HTML ile değiştirin.

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

Uygulamayı yerel olarak başlatma

Artık web sitenizi çalıştırabilir ve veritabanındaki verileri doğrudan işleyebilirsiniz.

1. Statik Web Uygulamaları CLI'sını yüklemek veya güncelleştirmek için npm kullanın. Durumunuz için en uygun komutu seçin.

   Yüklemek için kullanın npm install.

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

   Güncelleştirmek için kullanın npm update.

   npm update
   

2. Veritabanı yapılandırmasıyla statik web uygulamasını başlatın.

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

CLI başlatıldığından, staticwebapp.database.config.json dosyasında tanımlandığı gibi uç noktalar aracılığıyla veritabanınıza erişebilirsiniz.

Uç http://localhost:4280/data-api/graphql nokta GraphQL sorgularını ve mutasyonlarını kabul eder.

Verileri işleme

Aşağıdaki framework-agnostic komutları veritabanınızda tam CRUD işlemlerinin nasıl yapılacağını gösterir.

Her işlevin çıkışı tarayıcının konsol penceresinde görüntülenir.

CMD/CTRL + SHIFT + I tuşlarına basarak geliştirici araçlarını açın ve Konsol sekmesini seçin.

Tüm öğeleri listeleme

index.html etiketleri arasına script aşağıdaki kodu ekleyin.

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

Bu örnekte:

• GraphQL sorgusu veritabanından Id ve Name alanlarını seçer.
• Sunucuya geçirilen istek, özelliğin query sorgu tanımını barındırdığı bir yük gerektirir.
• Yanıt yükündeki veriler özelliğinde data.people.items bulunur.

Sayfayı yenileyin ve Liste düğmesini seçin.

Tarayıcının konsol penceresinde artık veritabanındaki tüm kayıtları listeleyen bir tablo görüntülenir.

İşte tarayıcınızda nasıl görünmesi gerektiğinin ekran görüntüsü.

Kimliğe göre alma

index.html etiketleri arasına script aşağıdaki kodu ekleyin.

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

Bu örnekte:

• GraphQL sorgusu veritabanından id ve Name alanlarını seçer.
• Sunucuya geçirilen istek, özelliğin query sorgu tanımını barındırdığı bir yük gerektirir.
• Yanıt yükündeki veriler özelliğinde data.person_by_pk bulunur.

Sayfayı yenileyin ve Al düğmesini seçin.

Tarayıcının konsol penceresinde artık veritabanından istenen tek kaydın listelendiği bir tablo görüntülenir.

Güncelleştir

index.html etiketleri arasına script aşağıdaki kodu ekleyin.

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

Bu örnekte:

• GraphQL sorgusu veritabanından id ve Name alanlarını seçer.
• query nesnesi özelliğinde GraphQL sorgusunu query tutar.
• GraphQL işlevine bağımsız değişken değerleri özelliği aracılığıyla query.variables geçirilir.
• Sunucuya geçirilen istek, özelliğin query sorgu tanımını barındırdığı bir yük gerektirir.
• Yanıt yükündeki veriler özelliğinde data.updatePerson bulunur.

Sayfayı yenileyin ve Güncelleştir düğmesini seçin.

Tarayıcının konsol penceresinde artık güncelleştirilmiş verileri gösteren bir tablo görüntülenir.

Oluşturma

index.html etiketleri arasına script aşağıdaki kodu ekleyin.

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

Bu örnekte:

• GraphQL sorgusu veritabanından id ve Name alanlarını seçer.
• query nesnesi özelliğinde GraphQL sorgusunu query tutar.
• GraphQL işlevine bağımsız değişken değerleri özelliği aracılığıyla query.variables geçirilir.
• Sunucuya geçirilen istek, özelliğin query sorgu tanımını barındırdığı bir yük gerektirir.
• Yanıt yükündeki veriler özelliğinde data.updatePerson bulunur.

Sayfayı yenileyin ve Oluştur düğmesini seçin.

Tarayıcının konsol penceresinde artık veritabanındaki yeni kaydı gösteren bir tablo görüntülenir.

Sil

index.html etiketleri arasına script aşağıdaki kodu ekleyin.

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

Bu örnekte:

• GraphQL sorgusu, alanı veritabanından seçer Id .
• query nesnesi özelliğinde GraphQL sorgusunu query tutar.
• GraphQL işlevine bağımsız değişken değerleri özelliği aracılığıyla query.variables geçirilir.
• Sunucuya geçirilen istek, özelliğin query sorgu tanımını barındırdığı bir yük gerektirir.
• Yanıt yükündeki veriler özelliğinde data.deletePerson bulunur.

Sayfayı yenileyin ve Sil düğmesini seçin.

Tarayıcının konsol penceresinde artık silme isteğinden gelen yanıtı gösteren bir tablo görüntülenir.

Kayıt silindi: 2

Artık sitenizle yerel olarak çalıştığınıza göre, artık bunu Azure'a dağıtabilirsiniz.

Sitenizi dağıtma

Bu siteyi üretim ortamına dağıtmak için yapılandırma dosyasını işlemeniz ve değişikliklerinizi sunucuya göndermeniz yeterlidir.

1. Yapılandırma değişikliklerini işleme.

   git commit -am "Add database configuration"
   

2. Değişikliklerinizi sunucuya gönderme.

   git push origin main
   

3. Web uygulamanızın derlanmasını bekleyin.

4. Tarayıcıda statik web uygulamanıza gidin.

5. Tüm öğeleri listelemek için Listele düğmesini seçin.

   Çıktı, bu ekran görüntüsünde gösterilene benzemelidir.

   

Veritabanını statik web uygulamanıza bağlama

Sitenizin Statik Web Apps örneği ile veritabanınız arasında bağlantı oluşturmak için aşağıdaki adımları kullanın.

1. Statik web uygulamanızı Azure portalında açın.

2. Ayarlar bölümünde Veritabanı bağlantısı'nı seçin.

3. Üretim bölümünün altında Var olan veritabanını bağla bağlantısını seçin.

4. Var olan veritabanını bağla penceresinde aşağıdaki değerleri girin:

   Özellik	Değer
   Veritabanı Türü	Açılan listeden veritabanı türünüzü seçin.
   Abonelik	Açılan listeden Azure aboneliğinizi seçin.
   Veritabanı Adı	Statik web uygulamanıza bağlamak istediğiniz veritabanının adını seçin.
   Kimlik Doğrulaması Türü	Bağlantı dizesi'ne tıklayın.

5. Tamam'ı seçin.

Veritabanınızın Statik Web Apps kaynağınıza bağlı olduğunu doğrulayın

Veritabanınızı statik web uygulamanıza bağladıktan ve sitenin oluşturulması tamamlandıktan sonra, veritabanı bağlantısını doğrulamak için aşağıdaki adımları kullanın.

1. Statik web uygulamanızı Azure portalında açın.

2. Temel Bileşenler bölümünde Statik Web Apps kaynağınızın URL'sini seçerek statik web uygulamanıza gidin.

3. Tüm öğeleri listelemek için Listele düğmesini seçin.

   Çıktı, bu ekran görüntüsünde gösterilene benzemelidir.

   

Kaynakları temizleme

Bu öğretici sırasında oluşturulan kaynakları kaldırmak istiyorsanız veritabanının bağlantısını kaldırmanız ve örnek verileri kaldırmanız gerekir.

1. Veritabanının bağlantısını kaldırma: Statik web uygulamanızı Azure portalında açın. Ayarlar bölümünde Veritabanı bağlantısı'nı seçin. Bağlı veritabanının yanında Ayrıntıları görüntüle'yi seçin. Veritabanı bağlantısı ayrıntıları penceresinde Bağlantıyı Kaldır düğmesini seçin.

2. Örnek verileri kaldırma: Veritabanınızda adlı MyTestPersonContainertabloyu silin.

Sonraki adımlar