Bagikan melalui

Tutorial: Menyiapkan distribusi global menggunakan Azure Cosmos DB untuk NoSQL

  • Berlaku untuk: ✅ NoSQL

Dalam artikel ini, kami menunjukkan cara menggunakan portal Azure untuk menyiapkan distribusi global Azure Cosmos DB lalu menyambungkan menggunakan API untuk NoSQL.

Artikel ini membahas tugas-tugas berikut ini:

  • Mengonfigurasikan distribusi global menggunakan portal Microsoft Azure
  • Mengonfigurasi distribusi global menggunakan API untuk NoSQLs

Menambahkan wilayah database global menggunakan portal Microsoft Azure

Azure Cosmos DB tersedia di semua wilayah Azure di seluruh dunia. Setelah memilih tingkat konsistensi default untuk akun database Anda, Anda dapat mengaitkan satu atau beberapa wilayah (tergantung pada tingkat konsistensi default kebutuhan distribusi global Anda).

  1. Di portal Azure, di bilah kiri, klik Azure Cosmos DB.

  2. Di halaman Azure Cosmos DB, pilih akun database untuk dimodifikasi.

  3. Di halaman akun, klik Meniru data secara global dari menu.

  4. Di halaman Meniru data secara global, pilih wilayah untuk ditambahkan atau dihapus dengan mengeklik wilayah di peta, lalu klik Simpan. Ada biaya untuk menambahkan wilayah, lihat halaman harga atau Mendistribusikan data secara global dengan artikel Azure Cosmos DB untuk informasi selengkapnya.

    Klik wilayah di peta untuk ditambahkan atau dihapus

Setelah Anda menambahkan wilayah kedua, opsi Failover Manual diaktifkan pada halaman Mereplikasi data secara global di portal. Anda dapat menggunakan opsi ini untuk menguji proses failover atau mengubah wilayah tulis utama. Setelah Anda menambahkan wilayah ketiga, opsi Prioritas Failover diaktifkan dalam halaman yang sama agar Anda bisa mengubah urutan failover untuk pembacaan data.

Memilih kawasan database global

Ada dua skenario umum untuk mengonfigurasi dua wilayah atau lebih:

  1. Memberikan akses latensi rendah ke data pengguna akhir di mana pun mereka berada di seluruh dunia
  2. Menambahkan ketahanan wilayah untuk kelangsungan bisnis dan pemulihan bencana (BCDR)

Untuk memberikan latensi rendah kepada pengguna akhir, disarankan agar Anda menyebarkan aplikasi dan Azure Cosmos DB di wilayah yang sesuai dengan lokasi pengguna aplikasi.

Untuk BCDR, sebaiknya tambahkan wilayah berdasarkan pasangan wilayah yang dijelaskan dalam artikel Replikasi lintas wilayah di Azure: Kesinambungan bisnis dan pemulihan bencana.

Menyambungkan ke wilayah pilihan menggunakan API untuk NoSQL

Untuk memanfaatkan distribusi global, aplikasi klien dapat menentukan daftar preferensi wilayah yang dipesan untuk digunakan untuk melakukan operasi dokumen. Berdasarkan konfigurasi akun Azure Cosmos DB, ketersediaan wilayah saat ini dan daftar preferensi yang ditentukan, titik akhir yang paling optimal akan dipilih oleh SDK SQL untuk melakukan operasi tulis dan baca.

Daftar preferensi ini ditentukan saat menginisialisasi koneksi menggunakan SDK SQL. SDK menerima parameter opsional PreferredLocations yang merupakan daftar berurutan wilayah Azure.

SDK akan secara otomatis mengirim semua tulisan ke wilayah tulis saat ini. Semua bacaan dikirim ke wilayah pertama yang tersedia di daftar lokasi pilihan. Jika permintaan gagal, klien akan gagal menurunkan daftar ke wilayah berikutnya.

SDK hanya akan mencoba membaca dari wilayah yang ditentukan di lokasi pilihan. Jadi, misalnya, jika akun Azure Cosmos DB tersedia di empat wilayah, tetapi klien hanya menentukan dua wilayah baca(non-tulis) dalam PreferredLocations, maka tidak ada bacaan yang disajikan di luar wilayah baca yang tidak ditentukan dalam PreferredLocations. Jika wilayah baca yang ditentukan dalam PreferredLocations daftar tidak tersedia, bacaan disajikan di luar wilayah tulis.

Aplikasi dapat memverifikasi titik akhir tulis saat ini dan membaca titik akhir yang dipilih oleh SDK dengan memeriksa dua properti, WriteEndpoint dan ReadEndpoint yang tersedia di SDK versi 1.8 ke atas. Jika properti PreferredLocations tidak diatur, semua permintaan dilayani dari region penulisan saat ini.

Jika Anda tidak menentukan lokasi pilihan tetapi menggunakan metode setCurrentLocation, SDK secara otomatis mengisi lokasi pilihan berdasarkan wilayah saat ini yang dijalankan klien. SDK mengurutkan wilayah berdasarkan kedekatannya dengan wilayah saat ini.

.NET SDK

SDK dapat digunakan tanpa perubahan kode apa pun. Dalam hal ini, SDK secara otomatis mengarahkan bacaan dan tulisan ke wilayah tulis saat ini. Di SDK .NET versi 1.8 dan yang lebih baru, parameter ConnectionPolicy untuk konstruktor DocumentClient memiliki properti yang disebut Microsoft.Azure.Documents. ConnectionPolicy.PreferredLocations. Properti ini berjenis Koleksi <string> dan harus berisi daftar nama wilayah. Nilai string diformat per kolom nama wilayah pada halaman Kawasan Azure tanpa spasi sebelum atau sesudah karakter pertama dan terakhir berturut-turut.

Titik akhir tulis dan baca saat ini tersedia di DocumentClient.WriteEndpoint dan DocumentClient.ReadEndpoint berturut-turut.

Nota

URL untuk titik akhir tidak boleh dianggap sebagai konstanta berumur panjang. Layanan dapat memperbarui ini kapan saja. SDK menangani perubahan ini secara otomatis.

Jika Anda menggunakan .NET V2 SDK, gunakan PreferredLocations properti untuk mengatur wilayah pilihan.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);

ConnectionPolicy connectionPolicy = new ConnectionPolicy();

//Setting read region selection preference
connectionPolicy.PreferredLocations.Add(LocationNames.WestUS); // first preference
connectionPolicy.PreferredLocations.Add(LocationNames.EastUS); // second preference
connectionPolicy.PreferredLocations.Add(LocationNames.NorthEurope); // third preference
// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    credential,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Atau, Anda dapat menggunakan SetCurrentLocation properti dan membiarkan SDK memilih lokasi pilihan berdasarkan kedekatan.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);

ConnectionPolicy connectionPolicy = new ConnectionPolicy();

connectionPolicy.SetCurrentLocation("West US 2"); /

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    credential,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Node.js/JavaScript

Nota

URL untuk titik akhir tidak boleh dianggap sebagai konstanta berumur panjang. Layanan dapat memperbarui ini kapan saja. SDK menangani perubahan ini secara otomatis.

Di bawah ini adalah contoh kode untuk Node.js/Javascript.

// Setting read region selection preference, in the following order -
// 1 - West US
// 2 - East US
// 3 - North Europe
const preferredLocations = ['West US', 'East US', 'North Europe'];

// initialize the connection
const client = new CosmosClient({ endpoint, aadCredentials: tokenCredential, connectionPolicy: { preferredLocations } });

Python SDK

Kode berikut menunjukkan cara mengatur lokasi pilihan dengan menggunakan SDK Python:

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, credential=token_credential, connectionPolicy)

Java V4 SDK

Kode berikut menunjukkan cara mengatur lokasi pilihan dengan menggunakan SDK Java:

ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .credential(tokenCredential)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

Konektor Spark 3

Anda dapat menentukan daftar regional pilihan menggunakan spark.cosmos.preferredRegionsListkonfigurasi, misalnya:

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "spark.cosmos.preferredRegionsList" -> "[West US, East US, North Europe]"
  // other settings
)

Go SDK (Kit Pengembangan Perangkat Lunak)

Untuk mengaktifkan multi-wilayah di aplikasi Anda, gunakan PreferredRegions di ClientOptions:

client, err := azcosmos.NewClient(endpoint, token, &azcosmos.ClientOptions{
	PreferredRegions: []string{"West US", "Central US"},
})

REST

Setelah akun database tersedia di beberapa wilayah, klien dapat mengkueri ketersediaannya dengan melakukan permintaan GET pada URI ini https://{databaseaccount}.documents.azure.com/

Layanan mengembalikan daftar wilayah dan URI titik akhir Azure Cosmos DB terkait untuk replika. Wilayah penulisan saat ini ditunjukkan dalam respons. Klien kemudian dapat memilih titik akhir yang sesuai untuk semua permintaan REST API lebih lanjut sebagai berikut.

Contoh tanggapan

{
    "_dbs": "//dbs/",
    "media": "//media/",
    "writableLocations": [
        {
            "Name": "West US",
            "DatabaseAccountEndpoint": "https://globaldbexample-westus.documents.azure.com:443/"
        }
    ],
    "readableLocations": [
        {
            "Name": "East US",
            "DatabaseAccountEndpoint": "https://globaldbexample-eastus.documents.azure.com:443/"
        }
    ],
    "MaxMediaStorageUsageInMB": 2048,
    "MediaStorageUsageInMB": 0,
    "ConsistencyPolicy": {
        "defaultConsistencyLevel": "Session",
        "maxStalenessPrefix": 100,
        "maxIntervalInSeconds": 5
    },
    "addresses": "//addresses/",
    "id": "globaldbexample",
    "_rid": "globaldbexample.documents.azure.com",
    "_self": "",
    "_ts": 0,
    "_etag": null
}
  • Semua permintaan PUT, POST, dan DELETE harus masuk ke URI tulis yang ditunjukkan
  • Semua GET dan permintaan pembacaan lainnya (misalnya kueri) dapat masuk ke endpoint pilihan klien

Menulis permintaan ke wilayah baca-saja akan gagal dengan kode kesalahan HTTP 403 ("Terlarang").

Jika wilayah tulis berubah setelah fase penemuan awal klien, tulisan berikutnya ke wilayah tulis sebelumnya akan gagal dengan kode kesalahan HTTP 403 ("Terlarang"). Klien kemudian harus meminta ulang daftar wilayah untuk mendapatkan wilayah penulisan yang diperbarui.

Inilah akhir dari tutorial ini. Anda dapat mempelajari cara mengelola konsistensi akun Anda yang direplikasi secara global dengan membaca tingkat Konsistensi di Azure Cosmos DB. Dan untuk informasi selengkapnya tentang cara kerja replikasi database global di Azure Cosmos DB, lihat Mendistribusikan data secara global dengan Azure Cosmos DB.

Langkah selanjutnya

Dalam tutorial ini, Anda telah melakukan tugas-tugas berikut:

  • Mengonfigurasikan distribusi global menggunakan portal Microsoft Azure
  • Mengonfigurasi distribusi global menggunakan API untuk NoSQLs

Anda sekarang dapat melanjutkan ke tutorial berikutnya untuk mempelajari cara mengembangkan secara lokal menggunakan emulator lokal Azure Cosmos DB.

Mengembangkan secara lokal dengan emulator

Mencoba melakukan perencanaan kapasitas untuk migrasi ke Azure Cosmos DB? Anda dapat menggunakan informasi tentang kluster database Anda yang ada saat ini untuk membuat perencanaan kapasitas.

  • Last updated on