Python kullanarak NoSQL için Azure Cosmos DB kullanmaya başlama
UYGULANANLAR: NoSQL
Bu makalede, Python SDK'sını kullanarak NoSQL için Azure Cosmos DB'ye nasıl bağlanabileceğiniz gösterilmektedir. Bağlandıktan sonra veritabanları, kapsayıcılar ve öğeler üzerinde işlemler gerçekleştirebilirsiniz.
Paket (PyPi) | Örnekler | API başvurusu | Kitaplık kaynak kodu | Geri Bildirim Ver
Ön koşullar
- Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
- NoSQL için Azure Cosmos DB hesabı. NoSQL hesabı için bir API oluşturun.
- Python 3.7 veya üzeri
- Azure Komut Satırı Arabirimi (CLI) veya Azure PowerShell
Projenizi ayarlama
Python kodunu çalıştırabileceğiniz bir ortam oluşturun.
Sanal bir ortamla, python paketlerini sisteminizin geri kalanını etkilemeden yalıtılmış bir ortama yükleyebilirsiniz.
Sanal ortama NoSQL için Azure Cosmos DB Python SDK'sını yükleyin.
pip install azure-cosmos
Python uygulamasını oluşturma
Ortamınızda yeni bir app.py dosyası oluşturun ve aşağıdaki kodu ekleyin:
import json
import os
import sys
import uuid
from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey
Yukarıdaki kod, makalenin geri kalanında kullanacağınız modülleri içeri aktarır.
NoSQL için Azure Cosmos DB'ye Bağlan
Azure Cosmos DB'nin NoSQL API'sine bağlanmak için CosmosClient sınıfının bir örneğini oluşturun. Bu sınıf, veritabanlarında tüm işlemleri gerçekleştirmek için başlangıç noktasıdır. CosmosClient sınıfını kullanarak NoSQL hesabına yönelik bir API'ye bağlanmanın üç yolu vardır:
- NoSQL uç noktası ve okuma/yazma anahtarı için API ile Bağlan
- NoSQL bağlantı dizesi için API ile Bağlan
- Microsoft Entra Id ile Bağlan
Uç nokta ve anahtarla Bağlan
CosmosClient oluşturucusunun iki gerekli parametresi vardır:
Parametre | Örnek değer | Tanım |
---|---|---|
url |
COSMOS_ENDPOINT ortam değişkeni |
Tüm istekler için kullanılacak NoSQL uç noktası API'si. |
credential |
COSMOS_KEY ortam değişkeni |
Kimlik doğrulaması sırasında kullanılacak hesap anahtarı veya kaynak belirteci. |
Hesap uç noktanızı ve anahtarınızı alma
resourceGroupName için bir kabuk değişkeni oluşturun.
# Variable for resource group name resourceGroupName="msdocs-cosmos-python-howto-rg"
az cosmosdb list
Komutunu kullanarak kaynak grubunuzdaki ilk Azure Cosmos DB hesabının adını alın ve accountName kabuk değişkeninde depolayın.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
komutunu kullanarak hesap için NoSQL uç nokta URI'sine yönelik API'yi
az cosmosdb show
alın.az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
komutuyla hesabın anahtar listesinden BİRİnCİl ANAHTAR'ı
az-cosmosdb-keys-list
bulun.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
URI ve BİRİnCİl ANAHTAR değerlerini kaydedin. Bu kimlik bilgilerini daha sonra kullanacaksınız.
Python kodunuz içinde URI ve BİRİnCİl ANAHTAR değerlerini kullanmak için, bunları uygulamayı çalıştıran yerel makinedeki yeni ortam değişkenlerinde kalıcı hale getirin.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Hesap uç noktası ve anahtarıyla CosmosClient oluşturma
ve ortam değişkenlerini parametre olarak kullanarak CosmosClient sınıfının COSMOS_ENDPOINT
COSMOS_KEY
yeni bir örneğini oluşturun.
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]
client = CosmosClient(url=ENDPOINT, credential=KEY)
bağlantı dizesi ile Bağlan
CosmosClient sınıfı, gerekli bir parametreyle bağlanmak için kullanabileceğiniz bir from_connection_string yöntemine sahiptir:
Parametre | Örnek değer | Tanım |
---|---|---|
conn_str |
COSMOS_CONNECTION_STRING ortam değişkeni |
NoSQL hesabı için API'ye bağlantı dizesi. |
credential |
COSMOS_KEY ortam değişkeni |
bağlantı dizesi yerine kullanılacak isteğe bağlı bir alternatif hesap anahtarı veya kaynak belirteci. |
Hesap bağlantı dizesi alma
az cosmosdb list
Komutunu kullanarak kaynak grubunuzdaki ilk Azure Cosmos DB hesabının adını alın ve accountName kabuk değişkeninde depolayın.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
komutuyla hesabın bağlantı dizesi listesinden BİRİnCİl BAĞLANTI DIZESİ'ni
az-cosmosdb-keys-list
bulun.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
Python kodunuz içinde BİRİnCİl BAĞLANTI DIZESİ değerini kullanmak için uygulamayı çalıştıran yerel makinede yeni bir ortam değişkeninde kalıcı hale getirmek.
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
bağlantı dizesi ile CosmosClient oluşturma
Tek parametre olarak ortam değişkeniyle COSMOS_CONNECTION_STRING
CosmosClient sınıfının yeni bir örneğini oluşturun.
CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]
client = CosmosClient.from_connection_string(conn_str=CONN_STR)
Microsoft kimlik platformu kullanarak Bağlan
Microsoft kimlik platformu ve Microsoft Entra Id kullanarak NoSQL hesabına yönelik API'nize bağlanmak için bir güvenlik sorumlusu kullanın. Sorumlunun tam türü, uygulama kodunuzu nerede barındırdığınıza bağlıdır. Aşağıdaki tablo bir hızlı başvuru kılavuzu görevi görür.
Uygulamanın çalıştığı yer | Güvenlik sorumlusu |
---|---|
Yerel makine (geliştirme ve test) | Kullanıcı kimliği veya hizmet sorumlusu |
Azure | Yönetilen kimlik |
Azure dışındaki sunucular veya istemciler | Hizmet sorumlusu |
Azure.Identity'i içeri aktarma
azure-identity paketi, tüm Azure SDK kitaplıkları arasında paylaşılan temel kimlik doğrulama işlevselliğini içerir.
azure-identity paketini ortamınıza aktarın.
pip install azure-identity
Varsayılan kimlik bilgisi uygulamasıyla CosmosClient oluşturma
Yerel bir makinede test ediyorsanız veya uygulamanız yönetilen kimlikler için doğrudan destekle Azure hizmetlerinde çalışacaksa bir örnek oluşturarak OAuth DefaultAzureCredential
belirteci alın.
app.py:
Bir uç nokta ve anahtarla Bağlan için yukarıdaki bölümde gösterildiği gibi bağlanacak uç noktayı alın ve bunu ortam değişkeni
COSMOS_ENDPOINT
olarak ayarlayın.DefaultAzureCredential öğesini içeri aktarın ve bunun bir örneğini oluşturun.
Endpoint ve kimlik bilgilerini parametre olarak kullanarak CosmosClient sınıfının yeni bir örneğini oluşturun.
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
Önemli
Çalışmayı etkinleştirmek DefaultAzureCredential
için doğru rolü ekleme hakkında ayrıntılı bilgi için bkz . Azure Cosmos DB hesabınız için Microsoft Entra Id ile rol tabanlı erişim denetimini yapılandırma. Özellikle rol oluşturma ve bunları bir asıl kimliğe atama bölümüne bakın.
Özel kimlik bilgisi uygulamasıyla CosmosClient oluşturma
Uygulamayı Azure dışına dağıtmayı planlıyorsanız, Python için Azure.Identity istemci kitaplığındaki diğer sınıfları kullanarak bir OAuth belirteci alabilirsiniz. Bu diğer sınıflar da sınıfından TokenCredential
türetilir.
Bu örnekte, istemci ve kiracı tanımlayıcılarının yanı sıra bir istemci gizli dizisi kullanarak bir örnek oluştururuz ClientSecretCredential
.
app.py:
Hizmet sorumlusu için ortam değişkenlerinden kimlik bilgisi bilgilerini alın. Bir uygulamayı Microsoft Entra Id'ye kaydederken istemci kimliğini, kiracı kimliğini ve istemci gizli dizisini alabilirsiniz. Microsoft Entra uygulamalarını kaydetme hakkında daha fazla bilgi için bkz. Uygulamayı Microsoft kimlik platformu kaydetme.
ClientSecretCredential'ı içeri aktarın ve parametre olarak ,
CLIENT_ID
veCLIENT_SECRET
ortam değişkenleriyleTENANT_ID
bir örnek oluşturun.Endpoint ve kimlik bilgilerini parametre olarak kullanarak CosmosClient sınıfının yeni bir örneğini oluşturun.
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)
Uygulamanızı derleme
Uygulamanızı oluştururken kodunuz öncelikli olarak dört tür kaynakla etkileşim kurar:
Azure Cosmos DB verileriniz için benzersiz üst düzey ad alanı olan NoSQL hesabı için API.
Hesabınızdaki kapsayıcıları düzenleyen veritabanları.
Veritabanınızdaki tek tek öğeler kümesini içeren kapsayıcılar.
Kapsayıcınızdaki bir JSON belgesini temsil eden öğeler.
Aşağıdaki diyagramda bu kaynaklar arasındaki ilişki gösterilmektedir.
En üstte bir Azure Cosmos DB hesabını gösteren hiyerarşik diyagram. Hesabın iki alt veritabanı düğümü vardır. Veritabanı düğümlerinden biri iki alt kapsayıcı düğümü içerir. Diğer veritabanı düğümü tek bir alt kapsayıcı düğümü içerir. Bu tek kapsayıcı düğümünde üç alt öğe düğümü vardır.
Her kaynak türü bir veya daha fazla ilişkili Python sınıfıyla temsil edilir. Zaman uyumlu programlama için en yaygın sınıfların listesi aşağıdadır. (azure.cosmos.aio ad alanı altında zaman uyumsuz programlama için benzer sınıflar vardır.)
Sınıf | Tanım |
---|---|
CosmosClient |
Bu sınıf, Azure Cosmos DB hizmeti için istemci tarafı mantıksal gösterimi sağlar. İstemci nesnesi, hizmette istekleri yapılandırmak ve yürütmek için kullanılır. |
DatabaseProxy |
Hizmette henüz var olabilen veya bulunmayabilecek bir veritabanı arabirimi. Bu sınıfın örneği doğrudan oluşturulamaz. Bunun yerine CosmosClient get_database_client yöntemini kullanmanız gerekir. |
ContainerProxy |
Belirli bir Cosmos DB kapsayıcısıyla etkileşime geçmek için bir arabirim. Bu sınıfın örneği doğrudan oluşturulamaz. Bunun yerine, var olan bir kapsayıcıyı almak için DatabaseProxy get_container_client yöntemini veya yeni bir kapsayıcı oluşturmak için create_container yöntemini kullanın. |
Aşağıdaki kılavuzlarda, uygulamanızı derlemek için bu sınıfların her birinin nasıl kullanılacağı gösterilmektedir.
Kılavuz | Tanım |
---|---|
Veritabanı oluşturma | Veritabanları oluşturma |
Kapsayıcı oluşturma | Kapsayıcı oluşturma |
Öğe örnekleri | Belirli bir öğeyi nokta okuma |
Ayrıca bkz.
Sonraki adımlar
Artık NoSQL hesabı için bir API'ye bağlandığınıza göre, veritabanlarını oluşturmak ve yönetmek için sonraki kılavuzu kullanın.