Mulai Cepat: Membuat Azure Cosmos DB dan kontainer menggunakan Bicep

  • Berlaku untuk: ✅ NoSQL

Azure Cosmos DB adalah database NoSQL cepat Microsoft dengan API terbuka untuk skala apa pun. Anda dapat menggunakan Azure Cosmos DB untuk membuat dan mengueri database kunci/nilai, dokumen, dan grafik dengan cepat. Tanpa kartu kredit atau langganan Azure, Anda dapat menyiapkan Coba akun Azure Cosmos DB gratis. Panduan cepat ini berfokus pada proses penyebaran file Bicep untuk membuat database Azure Cosmos DB dan kontainer dalam database tersebut. Anda nantinya dapat menyimpan data dalam kontainer ini.

Bicep adalah bahasa khusus domain (DSL) yang menggunakan sintaksis deklaratif untuk menyebarkan sumber daya Azure. Ini menyediakan sintaks yang ringkas, keamanan jenis yang dapat diandalkan, dan dukungan untuk penggunaan kembali kode. Bicep menawarkan pengalaman penulisan terbaik untuk solusi infrastructure-as-code di Azure.

Prerequisites

Langganan Azure atau akun uji coba Azure Cosmos DB gratis.

  • Jika Anda tidak memiliki akun Azure, buat akun gratis sebelum memulai.

Meninjau file Bicep

File Bicep yang digunakan dalam quickstart ini berasal dari Azure Quickstart Templates.

@description('Azure Cosmos DB account name, max length 44 characters')
param accountName string = 'sql-${uniqueString(resourceGroup().id)}'

@description('Location for the Azure Cosmos DB account.')
param location string = resourceGroup().location

@description('The primary region for the Azure Cosmos DB account.')
param primaryRegion string

@description('The secondary region for the Azure Cosmos DB account.')
param secondaryRegion string

@allowed([
  'Eventual'
  'ConsistentPrefix'
  'Session'
  'BoundedStaleness'
  'Strong'
])
@description('The default consistency level of the Cosmos DB account.')
param defaultConsistencyLevel string = 'Session'

@minValue(10)
@maxValue(2147483647)
@description('Max stale requests. Required for BoundedStaleness. Valid ranges, Single Region: 10 to 2147483647. Multi Region: 100000 to 2147483647.')
param maxStalenessPrefix int = 100000

@minValue(5)
@maxValue(86400)
@description('Max lag time (minutes). Required for BoundedStaleness. Valid ranges, Single Region: 5 to 84600. Multi Region: 300 to 86400.')
param maxIntervalInSeconds int = 300

@allowed([
  true
  false
])
@description('Enable system managed failover for regions')
param systemManagedFailover bool = true

@description('The name for the database')
param databaseName string = 'myDatabase'

@description('The name for the container')
param containerName string = 'myContainer'

@minValue(400)
@maxValue(1000000)
@description('The throughput for the container')
param throughput int = 400

var consistencyPolicy = {
  Eventual: {
    defaultConsistencyLevel: 'Eventual'
  }
  ConsistentPrefix: {
    defaultConsistencyLevel: 'ConsistentPrefix'
  }
  Session: {
    defaultConsistencyLevel: 'Session'
  }
  BoundedStaleness: {
    defaultConsistencyLevel: 'BoundedStaleness'
    maxStalenessPrefix: maxStalenessPrefix
    maxIntervalInSeconds: maxIntervalInSeconds
  }
  Strong: {
    defaultConsistencyLevel: 'Strong'
  }
}
var locations = [
  {
    locationName: primaryRegion
    failoverPriority: 0
    isZoneRedundant: false
  }
  {
    locationName: secondaryRegion
    failoverPriority: 1
    isZoneRedundant: false
  }
]

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-02-15-preview' = {
  name: toLower(accountName)
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    consistencyPolicy: consistencyPolicy[defaultConsistencyLevel]
    locations: locations
    databaseAccountOfferType: 'Standard'
    enableAutomaticFailover: systemManagedFailover
    disableKeyBasedMetadataWriteAccess: true
  }
}

resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-02-15-preview' = {
  parent: account
  name: databaseName
  properties: {
    resource: {
      id: databaseName
    }
  }
}

resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-02-15-preview' = {
  parent: database
  name: containerName
  properties: {
    resource: {
      id: containerName
      partitionKey: {
        paths: [
          '/myPartitionKey'
        ]
        kind: 'Hash'
      }
      indexingPolicy: {
        indexingMode: 'consistent'
        includedPaths: [
          {
            path: '/*'
          }
        ]
        excludedPaths: [
          {
            path: '/myPathToNotIndex/*'
          }
          {
            path: '/_etag/?'
          }
        ]
        compositeIndexes: [
          [
            {
              path: '/name'
              order: 'ascending'
            }
            {
              path: '/age'
              order: 'descending'
            }
          ]
        ]
        spatialIndexes: [
          {
            path: '/location/*'
            types: [
              'Point'
              'Polygon'
              'MultiPolygon'
              'LineString'
            ]
          }
        ]
      }
      defaultTtl: 86400
      uniqueKeyPolicy: {
        uniqueKeys: [
          {
            paths: [
              '/phoneNumber'
            ]
          }
        ]
      }
    }
    options: {
      throughput: throughput
    }
  }
}

output location string = location
output name string = database.name
output resourceGroupName string = resourceGroup().name
output resourceId string = database.id

Tiga sumber daya Azure yang ditentukan dalam file Bicep:

Tabel berikut menyoroti parameter dan output utama yang paling sering Anda tinjau atau sesuaikan dalam file Bicep ini.

Parameter atau output Nilai bawaan atau nilai contoh Cakupan dan catatan
accountName Nama unik yang dihasilkan Nama akun global Azure Cosmos DB.
databaseName myDatabase Nama database SQL API.
containerName myContainer Nama kontainer SQL API.
throughput 400 Throughput yang dialokasikan dalam RU/dtk (unit permintaan per detik).
partitionKeyPath /myPartitionKey Jalur kunci partisi logis.
defaultTtl -1 Waktu hidup dalam hitung detik; -1 berarti item tidak pernah kedaluwarsa.
Versi API 2023-11-15 Versi SQL API yang digunakan; perilaku dapat berubah dengan versi yang lebih baru.

Important

Penyedia Azure Resource Manager, Microsoft.DocumentDB/databaseAccounts, telah mempertahankan nama yang sama selama bertahun-tahun. Ini memastikan bahwa templat yang ditulis bertahun-tahun yang lalu masih kompatibel dengan penyedia yang sama meskipun nama layanan dan sub-layanan telah berubah.

Menerapkan file Bicep

  1. Simpan file Bicep sebagai main.bicep ke penyimpanan lokal komputer Anda.

  2. Sebarkan file Bicep menggunakan Azure CLI atau Azure PowerShell.

    az group create --name exampleRG --location eastus
az deployment group create --resource-group exampleRG --template-file main.bicep --parameters primaryRegion=<primary-region> secondaryRegion=<secondary-region>

    Nota

    Ganti <wilayah> utama dengan wilayah replika utama untuk akun Azure Cosmos DB, seperti westus. Ganti <wilayah> sekunder dengan wilayah replika sekunder untuk akun Azure Cosmos DB, seperti eastus.

    Nilai wilayah menggunakan format nama wilayah Azure (misalnya, eastus, westus2).

    Setelah penyebaran selesai, Anda akan melihat pesan yang menunjukkan penyebaran berhasil.

Cuplikan berikut menunjukkan contoh nilai parameter dan cara memverifikasi penyebaran.

az deployment group create \
  --resource-group exampleRG \
  --template-file main.bicep \
  --parameters primaryRegion=eastus secondaryRegion=westus

az cosmosdb sql database list --account-name <account-name> --resource-group exampleRG

Output yang diharapkan mencakup nama database yang Anda tentukan, seperti "name": "myDatabase".

Validasikan penggelaran

Gunakan portal Azure, Azure CLI, atau Azure PowerShell untuk mencantumkan sumber daya yang disebarkan dalam grup sumber daya.

az resource list --resource-group exampleRG

Membersihkan sumber daya

Jika Anda berencana untuk terus bekerja dengan panduan memulai cepat dan tutorial berikutnya, Anda mungkin ingin membiarkan sumber daya ini tetap ada. Jika tidak lagi diperlukan, gunakan portal Azure, Azure CLI, atau Azure PowerShell untuk menghapus grup sumber daya dan sumber dayanya.

az group delete --name exampleRG

Langkah berikutnya

Dalam mulai cepat ini, Anda membuat akun Azure Cosmos DB, database, dan kontainer dengan menggunakan file Bicep dan memvalidasi penyebaran. Untuk mempelajari lebih lanjut tentang Azure Cosmos DB dan Bicep, lanjutkan membaca artikel berikut.

  • Last updated on