Bagikan melalui

Mengembangkan secara lokal menggunakan emulator Azure Cosmos DB

  • Artikel

Kasus penggunaan umum untuk emulator adalah berfungsi sebagai database pengembangan saat Anda membangun aplikasi Anda. Menggunakan emulator untuk pengembangan dapat membantu Anda mempelajari karakteristik pembuatan dan pemodelan data untuk database seperti Azure Cosmos DB tanpa dikenakan biaya layanan apa pun. Selain itu, menggunakan emulator sebagai bagian dari alur kerja otomatisasi dapat memastikan bahwa Anda dapat menjalankan rangkaian pengujian integrasi yang sama. Anda dapat memastikan bahwa pengujian yang sama berjalan baik secara lokal pada komputer pengembangan Anda dan dari jarak jauh dalam pekerjaan integrasi berkelanjutan.

Prasyarat

Menginstal emulator

Ada beberapa variasi emulator dan setiap variasi memiliki proses penginstalan yang relatif tanpa gesekan.

Untuk memulai, dapatkan varian Linux dari gambar kontainer dari Microsoft Container Registry (MCR).

  1. mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Tarik gambar kontainer Linux dari registri kontainer ke host Docker lokal.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Periksa untuk memastikan bahwa gambar emulator tersedia di host Docker lokal Anda.

    docker images

Untuk memulai, dapatkan varian Linux dari gambar kontainer dari Microsoft Container Registry (MCR).

  1. mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Tarik gambar kontainer Linux menggunakan mongodb tag dari registri kontainer ke host Docker lokal.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Periksa untuk memastikan bahwa gambar emulator tersedia di host Docker lokal Anda.

    docker images

Varian kontainer Docker (Linux atau Windows) emulator tidak mendukung API untuk Apache Cassandra, API untuk Apache Gremlin, atau API untuk Table.

Memulai emulator

Setelah diunduh, mulai emulator dengan API yang Anda tentukan diaktifkan.

Varian kontainer Docker emulator tidak mendukung API untuk Apache Cassandra.

Varian kontainer Docker emulator tidak mendukung API untuk Apache Gremlin.

Varian kontainer Docker emulator tidak mendukung API untuk Table.

  1. Jalankan kontainer baru menggunakan gambar kontainer dan konfigurasi berikut:

    Deskripsi
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Opsional) Tentukan jumlah partisi yang akan digunakan.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Opsional) Aktifkan persistensi data antara emulator yang dijalankan.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opsional) Ambil alih alamat IP default emulator.

    Untuk sistem Linux, gunakan:

    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

    Untuk sistem Windows, gunakan:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250-10255:10250-10255"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Navigasi ke https://localhost:8081/_explorer/index.html untuk mengakses penjelajah data.

  1. Jalankan kontainer baru menggunakan gambar kontainer dan konfigurasi berikut:

    Deskripsi
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Tentukan versi titik akhir MongoDB yang akan digunakan. Titik akhir yang didukung meliputi: 3.2, , 3.6atau 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Opsional) Tentukan jumlah partisi yang akan digunakan.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Opsional) Aktifkan persistensi data antara emulator yang dijalankan.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opsional) Ambil alih alamat IP default emulator.

    Untuk sistem Linux, gunakan:

    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

    Untuk sistem Windows, gunakan:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250:10250"
    "--env", "AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Navigasi ke https://localhost:8081/_explorer/index.html untuk mengakses penjelajah data.

Mengimpor sertifikat TLS/SSL emulator

Impor sertifikat TLS/SSL emulator untuk menggunakan emulator dengan SDK pengembang pilihan Anda tanpa menonaktifkan TLS/SSL pada klien.

Varian kontainer Docker (Linux atau Windows) emulator tidak mendukung API untuk Apache Cassandra, API untuk Apache Gremlin, atau API untuk Table.

Sertifikat untuk emulator tersedia di jalur _explorer/emulator.pem pada kontainer yang sedang berjalan. Gunakan curl untuk mengunduh sertifikat dari kontainer yang sedang berjalan ke komputer lokal Anda.

  1. Dapatkan sertifikat dari kontainer yang sedang berjalan.

    Untuk sistem Linux, gunakan:

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    Untuk sistem Windows, gunakan:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

  2. Regenerasi bundel sertifikat dengan menggunakan perintah yang sesuai untuk sistem operasi Anda.

    Untuk sistem Linux berbasis Debian (misalnya, Ubuntu), gunakan:

    sudo update-ca-certificates

    Untuk sistem Linux berbasis Red Hat (misalnya, CentOS, Fedora), gunakan:

    sudo update-ca-trust

    Untuk sistem Windows, gunakan:

    certutil -f -addstore "Root" ~/emulatorcert.crt

    Untuk petunjuk lebih rinci, lihat dokumentasi khusus untuk sistem operasi Anda.

Sertifikat untuk emulator tersedia di jalur /_explorer/emulator.pem pada kontainer yang sedang berjalan.

  1. Unduh sertifikat dari kontainer yang sedang berjalan ke komputer lokal Anda.

    Untuk sistem Linux, gunakan:

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    Untuk sistem Windows, gunakan:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

    Catatan

    Anda mungkin perlu mengubah host (atau alamat IP) dan nomor port jika sebelumnya Anda telah memodifikasi nilai-nilai tersebut.

  2. Instal sertifikat sesuai dengan proses yang biasanya digunakan untuk sistem operasi Anda. Misalnya, di Linux Anda akan menyalin sertifikat ke /usr/local/share/ca-certificates/ jalur.

    Untuk sistem Linux, gunakan:

    cp ~/emulatorcert.crt /usr/local/share/ca-certificates/

    Untuk sistem Windows, gunakan:

    $parameters = @{
    FilePath = 'emulatorcert.crt'
    CertStoreLocation = 'Cert:\CurrentUser\Root'
}
Import-Certificate @parameters

  3. Untuk sistem linux, regenerasi bundel sertifikat dengan menggunakan perintah yang sesuai untuk distribusi Linux Anda.

    Untuk sistem Linux berbasis Debian (misalnya, Ubuntu), gunakan:

    sudo update-ca-certificates

    Untuk sistem Linux berbasis Red Hat (misalnya, CentOS, Fedora), gunakan:

    sudo update-ca-trust

    Untuk petunjuk lebih rinci, lihat dokumentasi khusus untuk sistem operasi Anda.

Menyambungkan ke emulator dari SDK

Setiap SDK menyertakan kelas klien yang biasanya digunakan untuk menyambungkan SDK ke akun Azure Cosmos DB Anda. Dengan menggunakan kredensial emulator, Anda dapat menghubungkan SDK ke instans emulator sebagai gantinya.

Gunakan Azure Cosmos DB API untuk NoSQL .NET SDK untuk menyambungkan ke emulator dari aplikasi .NET.

  1. Mulai dalam folder kosong.

  2. Membuat aplikasi konsol .NET baru

    dotnet new console

  3. Microsoft.Azure.Cosmos Tambahkan paket dari NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Buka file Program.cs.

  5. Hapus konten yang ada dalam file.

  6. Tambahkan blok penggunaan untuk Microsoft.Azure.Cosmos namespace layanan.

    using Microsoft.Azure.Cosmos;

  7. Buat instans baru menggunakan CosmosClient kredensial emulator.

    using CosmosClient client = new(
    accountEndpoint: "https://localhost:8081/",
    authKeyOrResourceToken: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

  8. Buat database dan kontainer baru menggunakan CreateDatabaseIfNotExistsAsync dan CreateContainerIfNotExistsAsync.

    Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks",
    throughput: 400
);

Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/id"
);

  9. Buat item baru dalam kontainer menggunakan UpsertItemAsync.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

await container.UpsertItemAsync(item);

  10. Jalankan aplikasi .NET.

    dotnet run

    Peringatan

    Jika Anda mendapatkan kesalahan SSL, Anda mungkin perlu menonaktifkan TLS/SSL untuk aplikasi Anda. Ini biasanya terjadi jika Anda mengembangkan di komputer lokal Anda, menggunakan emulator Azure Cosmos DB dalam kontainer, dan belum mengimpor sertifikat SSL kontainer. Untuk mengatasi hal ini, konfigurasikan opsi klien untuk menonaktifkan validasi TLS/SSL sebelum membuat klien:

    CosmosClientOptions options = new ()
{
    HttpClientFactory = () => new HttpClient(new HttpClientHandler()
    {
        ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    }),
    ConnectionMode = ConnectionMode.Gateway,
};

using CosmosClient client = new(
  ...,
  ...,
  clientOptions: options
);

Tip

Lihat panduan pengembang .NET untuk lebih banyak operasi yang dapat Anda lakukan menggunakan .NET SDK.

Gunakan driver MongoDB .NET untuk menyambungkan ke emulator dari aplikasi .NET.

  1. Mulai dalam folder kosong.

  2. Membuat aplikasi konsol .NET baru

    dotnet new console

  3. MongoDB.Driver Tambahkan paket dari NuGet.

    dotnet add package MongoDB.Driver

  4. Buka file Program.cs.

  5. Hapus konten yang ada dalam file.

  6. Tambahkan blok penggunaan untuk MongoDB.Driver namespace layanan.

    using MongoDB.Driver;

  7. Buat instans baru menggunakan MongoClient kredensial emulator.

    var client = new MongoClient(
    "mongodb://localhost:C2y6yDjf5%2FR%2Bob0N8A7Cgv30VRDJIWEHLM%2B4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw%2FJw%3D%3D@localhost:10255/admin?ssl=true&retrywrites=false"
);

  8. Dapatkan database dan kontainer menggunakan GetDatabase dan GetCollection<>.

    var database = client.GetDatabase("cosmicworks");

var collection = database.GetCollection<dynamic>("products");

  9. Buat item baru di XXX menggunakan InsertOneAsync.

    var item = new
{
    name = "Kiama classic surfboard"
};

await collection.InsertOneAsync(item);

  10. Jalankan aplikasi .NET.

    dotnet run

Gunakan driver .NET Apache Cassandra untuk menyambungkan ke emulator dari aplikasi .NET.

  1. Mulai dalam folder kosong.

  2. Membuat aplikasi konsol .NET baru

    dotnet new console

  3. CassandraCSharpDriver Tambahkan paket dari NuGet.

    dotnet add package CassandraCSharpDriver

  4. Buka file Program.cs.

  5. Hapus konten yang ada dalam file.

  6. Tambahkan blok penggunaan untuk Cassandra namespace layanan.

    using Cassandra;

  7. Buat instans baru menggunakan Cluster kredensial emulator. Buat sesi baru menggunakan Connect.

    var options = new SSLOptions(
    sslProtocol: System.Security.Authentication.SslProtocols.Tls12,
    checkCertificateRevocation: true,
    remoteCertValidationCallback: (_, _, _, policyErrors) => policyErrors == System.Net.Security.SslPolicyErrors.None);

using var cluster = Cluster.Builder()
    .WithCredentials(
        username: "localhost",
        password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
    )
    .WithPort(
        port: 10350
    )
    .AddContactPoint(
        address: "localhost"
    )
    .WithSSL(
        sslOptions: options
    )
    .Build();

using var session = cluster.Connect();

  8. Buat database dan kontainer baru menggunakan PrepareAsync dan ExecuteAsync.

    var createKeyspace = await session.PrepareAsync("CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'basicclass', 'replication_factor': 1};");
await session.ExecuteAsync(createKeyspace.Bind());

var createTable = await session.PrepareAsync("CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)");
await session.ExecuteAsync(createTable.Bind());

  9. Buat item baru dalam tabel menggunakan ExecuteAsync. Gunakan Bind untuk menetapkan properti ke item.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

var createItem = await session.PrepareAsync("INSERT INTO cosmicworks.products (id, name) VALUES (?, ?)");

var createItemStatement = createItem.Bind(item.id, item.name);

await session.ExecuteAsync(createItemStatement);

  10. Jalankan aplikasi .NET.

    dotnet run

Penting

Sebelum memulai, API untuk Apache Gremlin mengharuskan Anda membuat sumber daya di emulator. Buat database bernama db1 dan kontainer bernama coll1. Pengaturan throughput tidak relevan untuk panduan ini dan dapat diatur serendah yang Anda inginkan.

Gunakan driver .NET Apache Gremlin untuk menyambungkan ke emulator dari aplikasi .NET.

  1. Mulai dalam folder kosong.

  2. Membuat aplikasi konsol .NET baru

    dotnet new console

  3. Gremlin.Net Tambahkan paket dari NuGet.

    dotnet add package Gremlin.Net

  4. Buka file Program.cs.

  5. Hapus konten yang ada dalam file.

  6. Tambahkan blok penggunaan untuk Gremlin.Net.Driver namespace layanan.

    using Gremlin.Net.Driver;

  7. Buat instans GremlinServer baru dan GremlinClient gunakan kredensial emulator.

    var server = new GremlinServer(
    hostname: "localhost",
    port: 65400,
    username: "/dbs/db1/colls/coll1",
    password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

  8. Bersihkan grafik menggunakan SubmitAsync.

    await client.SubmitAsync(
    requestScript: "g.V().drop()"
);

  9. Gunakan SubmitAsync lagi untuk menambahkan item baru ke grafik dengan parameter yang ditentukan.

    await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', prop_id).property('name', prop_name)",
    bindings: new Dictionary<string, object>
    {
        { "prop_id", "68719518371" },
        { "prop_name", "Kiama classic surfboard" }
    }
);

  10. Jalankan aplikasi .NET.

    dotnet run

Gunakan Azure Tables SDK untuk .NET untuk menyambungkan ke emulator dari aplikasi .NET.

  1. Mulai dalam folder kosong.

  2. Membuat aplikasi konsol .NET baru

    dotnet new console

  3. Azure.Data.Tables Tambahkan paket dari NuGet.

    dotnet add package Azure.Data.Tables

  4. Buka file Program.cs.

  5. Hapus konten yang ada dalam file.

  6. Tambahkan blok penggunaan untuk Azure.Data.Tables namespace layanan.

    using Azure.Data.Tables;

  7. Buat instans baru menggunakan TableServiceClient kredensial emulator.

    var serviceClient = new TableServiceClient(
    connectionString: "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;"
);

  8. Gunakan GetTableClient untuk membuat instans TableClient baru dengan nama tabel. Kemudian pastikan tabel ada menggunakan CreateIfNotExistsAsync.

    var client = serviceClient.GetTableClient(
    tableName: "cosmicworksproducts"
);

await client.CreateIfNotExistsAsync();

  9. Buat jenis baru record untuk item.

    public record Product : Azure.Data.Tables.ITableEntity
{
    public required string RowKey { get; set; }

    public required string PartitionKey { get; set; }

    public required string Name { get; init; }

    public Azure.ETag ETag { get; set; }

    public DateTimeOffset? Timestamp { get; set; }
}

  10. Buat item baru dalam tabel menggunakan UpsertEntityAsync dan Replace mode .

    var item = new Product
{
    RowKey = "68719518371",
    PartitionKey = "Surfboards",
    Name = "Kiama classic surfboard",
    Timestamp = DateTimeOffset.Now
};

await client.UpsertEntityAsync(
    entity: item,
    mode: TableUpdateMode.Replace
);

  11. Jalankan aplikasi .NET.

    dotnet run

Menggunakan emulator dalam alur kerja GitHub Actions CI

Untuk menjalankan beban kerja integrasi berkelanjutan yang secara otomatis memvalidasi aplikasi Anda, gunakan emulator Azure Cosmos DB dengan rangkaian pengujian dari kerangka kerja pilihan Anda. Emulator Azure Cosmos DB telah diinstal sebelumnya dalam varian runner yang dihosting windows-latest GitHub Action.

Jalankan rangkaian pengujian menggunakan driver pengujian bawaan untuk .NET dan kerangka kerja pengujian seperti MSTest, NUnit, atau XUnit.

  1. Validasi bahwa rangkaian pengujian unit untuk aplikasi Anda berfungsi seperti yang diharapkan.

    dotnet test

  2. Buat alur kerja baru di repositori GitHub Anda dalam file bernama .github/workflows/ci.yml.

  3. Tambahkan pekerjaan ke alur kerja Anda untuk memulai emulator Azure Cosmos DB menggunakan PowerShell dan jalankan rangkaian pengujian unit Anda.

    name: Continuous Integration
on:
  push:
    branches:
      - main
jobs:
  unit_tests:
    name: Run .NET unit tests
    runs-on: windows-latest
    steps:
      - name: Checkout (GitHub)
        uses: actions/checkout@v3
      - name: Start Azure Cosmos DB emulator
        run: |
          Write-Host "Launching Cosmos DB Emulator"
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator
      - name: Run .NET tests
        run: dotnet test

    Catatan

    Mulai emulator dari baris perintah menggunakan berbagai argumen atau perintah PowerShell. Untuk informasi selengkapnya, lihat argumen baris perintah emulator.

Langkah selanjutnya

Tinjau catatan rilis emulator