Gunakan perintah dan fitur notebook bawaan di notebook Azure Cosmos DB C# (pratinjau)

  • Artikel
  • 4 menit untuk membaca

BERLAKU UNTUK: SQL API

Notebook Jupyter bawaan di Microsoft Azure Cosmos DB memudahkan Anda menganalisis dan memvisualisasikan data Anda dari portal Microsoft Azure. Artikel ini menjelaskan cara menggunakan perintah dan fitur notebook bawaan untuk melakukan operasi umum di notebook C#.

pasang paket NuGet baru

Setelah mengaktifkan dukungan notebook untuk akun Azure Cosmos, Anda bisa membuka notebook baru dan memasang paket.

Di sel kode baru, sisipkan dan jalankan kode berikut, ganti PackageToBeInstalled dengan paket NuGet yang diinginkan, dan optionalVersion dengan versi paket tertentu jika diinginkan.

#r "nuget: PackageToBeInstalled, optionalVersion"

Anda dapat memasang beberapa paket NuGet di sel yang sama. Paket ini akan tersedia untuk digunakan dari notebook apa pun di ruang kerja akun Azure Cosmos.

Saat ini, ruang kerja notebook C# tidak mendukung resolusi rekursif paket NuGet. Jika paket NuGet memiliki dependensi pada paket NuGet lain yang saat ini tidak diinstal, Anda harus secara eksplisit mereferensikannya bersama dengan paket induk.

Tip

Jika notebook Anda memerlukan paket kustom, kami menyarankan agar Anda menambahkan sel ke notebook Anda untuk menginstal paket dan menjadikannya sel pertama. Ini mengurangi kemungkinan konflik dengan paket lain yang dimuat Microsoft Azure Cosmos DB secara default. Juga mudah untuk menginstal ulang paket jika Anda mengatur ulang ruang kerja, yang menghapus semua paket.

Gunakan Microsoft Azure Cosmos DB .NET SDK bawaan

Versi 3 dari Microsoft Azure Cosmos DB Python SDK untuk SQL API dipasang dan disertakan dalam lingkungan notebook untuk akun Azure Cosmos.

Buat instans untuk CosmosClient menjalankan operasi SDK apa pun.

Contohnya:

// Include usings
using System;
using Microsoft.Azure.Cosmos; //namespace for Azure Cosmos DB .NET V3 SDK
using System.Collections;

// Initialize a new instance of CosmosClient using the built-in account endpoint and key parameters
CosmosClient cosmosClient = new CosmosClient(Cosmos.Endpoint, Cosmos.Key);

// Create a new database and container with 400 RU/s
Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync("DatabaseName");
Container container = await database.CreateContainerIfNotExistsAsync("ContainerName", "/partitionKey", 400);

Untuk mempelajari lebih lanjut, lihat sampel.NET V3 SDK.

Penting

Microsoft Azure Cosmos DB .NET SDK bawaan hanya didukung untuk akun SQL (Core) API. Untuk API lain, Anda harus menginstal driver Python yang relevan yang sesuai dengan API.

Mengatur opsi kustom menggunakan CosmosClientOptions

Untuk fleksibilitas lebih lanjut, Anda dapat mengatur properti CosmosClientOptions kustom dan meneruskannya dalam instans CosmosClient Anda. Anda dapat menggunakan properti ini untuk:

  • Tetapkan nama aplikasi dalam akhiran agen pengguna untuk menyertakannya dalam setiap permintaan.
  • Set wilayah pilihan untuk digunakan saat menjalankan operasi terhadap layanan.
  • Set kebijakan percobaan ulang khusus untuk menangani permintaan dengan tarif terbatas.

Lihat artikel referensi COSMOSClientOptions API untuk semua pengaturan yang didukung. Berikut ini adalah contoh yang memperlihatkan cara mengatur cosmosClientOptions properti:

using Microsoft.Azure.Cosmos;

// Configure CosmosClientOptions
var cosmosClientOptions = new CosmosClientOptions
{
    ApplicationName = "ContosoNotebookAppName",
    ApplicationRegion = Regions.RegionName, // By default, this is the region you first created your account in
    MaxRetryAttemptsOnRateLimitedRequests = 9, // By default, this value is 9
};

var client = new CosmosClient(Cosmos.Endpoint, Cosmos.Key, cosmosClientOptions);

Mengakses titik akhir akun dan variabel kunci utama

Anda dapat mengakses titik akhir bawaan dan kunci akun Azure Cosmos di mana notebook Anda ada.

var key = Cosmos.Key;
var endpoint = Cosmos.Endpoint;

Penting

Variabel Cosmos.Key dan Cosmos.Endpoint hanya berlaku untuk SQL API. Untuk API lain, temukan titik akhir dan kunci di bilah String Koneksi atau Kunci di akun Microsoft Azure Cosmos Anda.

Dalam kode C#, Anda dapat menggunakan sintaks Display.AsMarkdown() dengan interpolasi string untuk mencetak output konsol yang akan muncul saat Anda menjalankan sel.

Contohnya:

// Print text in the output
Display.AsMarkdown($"Hello world!");

// Print a variable in the output
for (int i = 0; i < 5; i++) {
    Display.AsMarkdown($"Printing out variable: {i}");
}

Penting

Sintaks Console.WriteLine() saat ini tidak didukung di notebook C#. Gunakan Display.AsMarkdown untuk mencetak keluaran konsol dari program Anda.

Menggunakan penjelajah data nteract bawaan

Anda dapat menggunakan penjelajah data nteract bawaan untuk memfilter dan memvisualisasikan kumpulan item. Dalam sel, letakkan variabel yang ingin Anda visualisasikan di baris terakhir, yang secara otomatis ditampilkan dalam nteract saat Anda menjalankan sel.

Misalnya, dalam contoh GetingStarted_Csharp.ipynb, kita dapat mencetak variabel dengan hasil kita, telemetryEvents. Lihat GettingStarted_Csharp.ipynb untuk seluruh sampel.

Csharp query cell

nteract data explorer

Menggunakan penampil kamus bawaan

Anda dapat menggunakan penampil kamus bawaan untuk melihat variabel. Dalam sel, letakkan variabel yang ingin Anda visualisasikan di baris terakhir, yang secara otomatis ditampilkan dalam nteract saat Anda menjalankan sel.

Built-in dictionary viewer

Mengunggah item JSON ke kontainer

Anda dapat menggunakan %%upload perintah ajaib untuk mengunggah data dari file JSON ke kontainer Azure Cosmos tertentu. Gunakan perintah berikut untuk mengunggah item:

%%upload --databaseName {database_id} --containerName {container_id} --url {url_location_of_file}
  • Mengganti{database_id} dan {container_id} dengan nama database dan kontainer di akun Azure Cosmos Anda.
  • Mengganti {url_location_of_file} dengan lokasi file JSON Anda. File harus merupakan array obyek JSON yang berlaku dan seharusnya bisa diakses melalui Internet publik.

Contohnya:

%%upload --database databaseName --container containerName --url 
https://contoso.com/path/to/data.json

Documents successfully uploaded to ContainerName
Total number of documents imported : 2654
Total time taken : 00:00:38.1228087 hours
Total RUs consumed : 25022.58

Dengan statistik output, Anda dapat menghitung RU/dtk efektif yang digunakan untuk mengunggah item. Misalnya, jika 25.000 RU yang digunakan lebih dari 38 detik, RU/dtk yang efektif adalah 25.000 RU / 38 detik = 658 RU/dtk.

Menjalankan notebook lain di notebook saat ini

Anda bisa menggunakan %%run perintah ajaib untuk menjalankan notebook lain di ruang kerja Anda dari notebook Anda saat ini. Gunakan sintaks:

%%run ./path/to/{notebookName}.ipynb

Mengganti {notebookName} dengan nama notebook yang ingin Anda jalankan. Notebook harus berada di 'Ruang Kerja Notebooks Saya' saat ini.

Mengatur ulang ruang kerja notebook

Untuk mengatur ulangt ruang kerja notebook ke pengaturan default, pilih Reset Ruang Kerja pada bilah perintah. Cara Ini akan menghapus paket yang dipasang kustom dan memulai ulang server Jupyter. Notebook, file, dan sumber daya Azure Cosmos Anda tidak akan terpengaruh.

Reset notebooks workspace

Langkah berikutnya