Share via

Mulai menggunakan Azure Cosmos DB untuk NoSQL menggunakan Python

  • Artikel

BERLAKU UNTUK: NoSQL

Artikel ini memperlihatkan kepada Anda cara menyambungkan ke Azure Cosmos DB for NoSQL menggunakan Python SDK. Setelah tersambung, Anda dapat melakukan operasi pada database, kontainer, dan item.

Paket (PyPi) | Sampel | kode | sumber pustaka referensi | API Berikan Umpan Balik

Prasyarat

Menyiapkan proyek Anda

Buat lingkungan tempat Anda dapat menjalankan kode Python.

Dengan lingkungan virtual, Anda dapat menginstal paket Python di lingkungan terisolasi tanpa memengaruhi sisa sistem Anda.

Instal Azure Cosmos DB untuk NoSQL Python SDK di lingkungan virtual.

pip install azure-cosmos

Membuat aplikasi Python

Di lingkungan Anda, buat file app.py baru dan tambahkan kode berikut ke dalamnya:

import json
import os
import sys
import uuid

from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey

Kode sebelumnya mengimpor modul yang akan Anda gunakan di sisa artikel.

Koneksi ke Azure Cosmos DB for NoSQL

Untuk menyambungkan ke API untuk NoSQL Azure Cosmos DB, buat instans kelas CosmosClient . Kelas ini adalah titik awal untuk melakukan semua operasi terhadap database. Ada tiga cara untuk terhubung ke API untuk akun NoSQL menggunakan kelas CosmosClient :

Sambungkan dengan titik akhir dan kunci

Konstruktor untuk CosmosClient memiliki dua parameter yang diperlukan:

Parameter Contoh nilai Deskripsi
url COSMOS_ENDPOINT Variabel lingkungan API untuk titik akhir NoSQL yang akan digunakan untuk semua permintaan.
credential COSMOS_KEY Variabel lingkungan Kunci akun atau token sumber daya yang akan digunakan saat mengautentikasi.

Mengambil titik akhir dan kunci akun Anda

  1. Buat variabel shell untuk resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-python-howto-rg"

  2. Gunakan perintah az cosmosdb list untuk mengambil nama akun Azure Cosmos DB pertama di grup sumber daya Anda dan simpan di variabel shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Dapatkan API untuk URI titik akhir NoSQL untuk akun menggunakan az cosmosdb show perintah .

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Temukan KUNCI PRIMER dari daftar kunci untuk akun dengan perintah az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Catat nilai URI dan KUNCI PRIMER. Anda akan menggunakan info masuk ini nanti.

Untuk menggunakan nilai URI dan KUNCI PRIMER dalam kode Python Anda, pertahankan ke variabel lingkungan baru pada komputer lokal yang menjalankan aplikasi.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Membuat CosmosClient dengan titik akhir dan kunci akun

Buat instans baru kelas CosmosClient dengan variabel lingkungan COSMOS_ENDPOINT dan COSMOS_KEY sebagai parameter.

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]

client = CosmosClient(url=ENDPOINT, credential=KEY)

Menghubungkan dengan string koneksi

Kelas CosmosClient memiliki metode from_connection_string yang dapat Anda gunakan untuk terhubung dengan satu parameter yang diperlukan:

Parameter Contoh nilai Deskripsi
conn_str COSMOS_CONNECTION_STRING Variabel lingkungan string koneksi ke API untuk akun NoSQL.
credential COSMOS_KEY Variabel lingkungan Kunci akun alternatif opsional atau token sumber daya untuk digunakan alih-alih yang ada di string koneksi.

Mengambil string koneksi akun Anda

  1. Gunakan perintah az cosmosdb list untuk mengambil nama akun Azure Cosmos DB pertama di grup sumber daya Anda dan simpan di variabel shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Temukan STRING KONEKSI UTAMA dari daftar string koneksi untuk akun dengan perintah az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Untuk menggunakan nilai STRING KONEKSI UTAMA dalam kode Python Anda, pertahankan ke variabel lingkungan baru pada komputer lokal yang menjalankan aplikasi.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Membuat CosmosClient dengan string koneksi

Buat instans baru kelas CosmosClient dengan variabel lingkungan COSMOS_CONNECTION_STRING sebagai satu-satunya parameter.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Koneksi menggunakan platform identitas Microsoft

Untuk menyambungkan ke API Anda untuk akun NoSQL menggunakan platform identitas Microsoft dan ID Microsoft Entra, gunakan prinsip keamanan. Jenis prinsipal yang tepat akan bergantung pada tempat Anda menghosting kode aplikasi. Tabel di bawah ini berfungsi sebagai panduan referensi singkat.

Tempat aplikasi berjalan Prinsip keamanan
Komputer lokal (pengembangan dan pengujian) Identitas pengguna atau perwakilan layanan
Azure Identitas Terkelola
Server atau klien di luar Azure Perwakilan layanan

Mengimpor Azure.Identity

Paket identitas azure berisi fungsionalitas autentikasi inti yang dibagikan di antara semua pustaka Azure SDK.

Impor paket identitas azure ke lingkungan Anda.

pip install azure-identity

Membuat CosmosClient dengan implementasi kredensial default

Jika Anda melakukan pengujian pada mesin lokal, atau aplikasi Anda akan berjalan di layanan Azure dengan dukungan langsung untuk identitas terkelola, dapatkan token OAuth dengan membuat instans DefaultAzureCredential.

Di app.py Anda:

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Penting

Untuk detail tentang cara menambahkan peran yang benar agar berfungsi DefaultAzureCredential , lihat Mengonfigurasi kontrol akses berbasis peran dengan ID Microsoft Entra untuk akun Azure Cosmos DB Anda. Secara khusus, lihat bagian tentang membuat peran dan menetapkannya ke ID utama.

Membuat CosmosClient dengan implementasi kredensial kustom

Jika Anda berencana untuk menyebarkan aplikasi ke luar Azure, Anda dapat memperoleh token OAuth dengan menggunakan kelas lain di pustaka klien Azure.Identity untuk Python. Kelas-kelas lain ini juga berasal dari kelas TokenCredential.

Untuk contoh ini, kami membuat instans ClientSecretCredential dengan menggunakan pengidentifikasi klien dan penyewa, bersama dengan rahasia klien.

Di app.py Anda:

  • Dapatkan informasi kredensial dari variabel lingkungan untuk perwakilan layanan. Anda dapat memperoleh ID klien, ID penyewa, dan rahasia klien saat mendaftarkan aplikasi di ID Microsoft Entra. Untuk informasi selengkapnya tentang mendaftarkan aplikasi Microsoft Entra, lihat Mendaftarkan aplikasi dengan platform identitas Microsoft.

  • Impor ClientSecretCredential dan buat instans dengan TENANT_IDvariabel lingkungan , , CLIENT_IDdan CLIENT_SECRET sebagai parameter.

  • Buat instans baru kelas CosmosClient dengan TITIK AKHIR dan kredensial sebagai parameter.

from azure.identity import ClientSecretCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
TENANT_ID = os.environ["TENANT_ID"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]

credential = ClientSecretCredential(
    tenant_id=TENANT_ID, client_id=CLIENT_ID, client_secret=CLIENT_SECRET
)

client = CosmosClient(ENDPOINT, credential)

Bangun aplikasi Anda

Saat Anda membangun aplikasi, kode Anda utamanya akan berinteraksi dengan empat jenis sumber daya:

  • API untuk akun NoSQL, yang merupakan namespace layanan tingkat atas unik untuk data Azure Cosmos DB Anda.

  • Database, yang mengatur kontainer di akun Anda.

  • Kontainer, yang berisi sekumpulan item individual dalam database Anda.

  • Item, yang mewakili dokumen JSON dalam kontainer Anda.

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Setiap jenis sumber daya diwakili oleh satu atau beberapa kelas Python terkait. Berikut adalah daftar kelas yang paling umum untuk pemrograman sinkron. (Ada kelas serupa untuk pemrograman asinkron di bawah namespace azure.cosmos.aio .)

Kelas Deskripsi
CosmosClient Kelas ini menyediakan representasi logis sisi klien untuk layanan Azure Cosmos DB. Klien ini digunakan untuk mengonfigurasi dan menjalankan permintaan terhadap layanan.
DatabaseProxy Antarmuka ke database yang mungkin, atau mungkin belum ada di layanan. Kelas ini tidak boleh diinstansiasi secara langsung. Sebagai gantinya, Anda harus menggunakan metode cosmosClient get_database_client .
ContainerProxy Antarmuka untuk berinteraksi dengan kontainer Cosmos DB tertentu. Kelas ini tidak boleh diinstansiasi secara langsung. Sebagai gantinya, gunakan metode databaseProxy get_container_client untuk mendapatkan kontainer yang sudah ada, atau metode create_container untuk membuat kontainer baru.

Panduan berikut menunjukkan cara menggunakan masing-masing kelas ini untuk membangun aplikasi Anda.

Panduan Deskripsi
Membuat database Membuat database
Membuat kontainer Membuat kontainer
Contoh item Membaca poin item tertentu

Baca juga

Langkah berikutnya

Sekarang setelah Anda tersambung ke API untuk akun NoSQL, gunakan panduan berikutnya untuk membuat dan mengelola database.

Membuat database di Azure Cosmos DB untuk NoSQL menggunakan Python