Tutorial: Menyiapkan distribusi global Azure Cosmos DB menggunakan API untuk NoSQL

  • Artikel

BERLAKU UNTUK: NoSQL

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

Artikel ini membahas tugas-tugas berikut ini:

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

Menambahkan wilayah database global menggunakan portal 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 Meniru 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 pada halaman yang sama sehingga Anda dapat mengubah urutan failover untuk bacaan.

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. Menambah ketahanan daerah untuk kelanjutan 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 akan 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 akan disajikan di luar wilayah baca yang tidak ditentukan di PreferredLocations. Jika wilayah baca yang ditentukan di daftar PreferredLocations tidak tersedia, bacaan akan 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 PreferredLocations properti tidak ditetapkan, semua permintaan akan dilayani dari wilayah tulis 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 memerintahkan wilayah berdasarkan kedekatan suatu wilayah 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.

Catatan

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 SDK .NET V2, gunakan PreferredLocations properti untuk mengatur wilayah pilihan.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
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,
    accountKey,
    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);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

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

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

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

Node.js/JavaScript

Catatan

URL untuk titik akhir tidak boleh dianggap sebagai konstanta berumur panjang. Layanan dapat memperbarui ini kapan saja. SDK akan 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, key, 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, {'masterKey': MASTER_KEY}, connectionPolicy)

Java V4 SDK

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

SDK Java V4 (Maven com.azure::azure-cosmos) API Async


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

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

Konektor Spark 3

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

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

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 ini akan mengembalikan daftar wilayah dan URI titik akhir Azure Cosmos DB yang sesuai untuk replika. Wilayah tulis saat ini akan ditunjukkan dalam respons. Klien kemudian dapat memilih titik akhir yang sesuai untuk semua permintaan REST API lebih lanjut sebagai berikut.

Contoh respons

{
    "_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 baca-saja lainnya (misalnya kueri) dapat masuk ke titik akhir 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 MENDAPATKAN daftar wilayah lagi untuk mendapatkan wilayah tulis 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 berikutnya

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

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

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

Mengembangkan secara lokal dengan emulator

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