Hızlı Başlangıç: MongoDB sürücüsü ile Python için MongoDB için Azure Cosmos DB

  • Makale

ŞUNLAR IÇIN GEÇERLIDIR: MongoDB

Azure Cosmos DB kaynağınızda veritabanları, koleksiyonlar ve belgeler oluşturmak için PyMongo paketini kullanmaya başlayın. Paketi yüklemek için bu adımları izleyin ve temel görevler için örnek kodu deneyin.

Dekont

Örnek kod parçacıkları GitHub'da Python projesi olarak kullanılabilir.

Bu hızlı başlangıçta, Python , PyMongo için açık kaynak MongoDB istemci sürücülerinden birini kullanarak MongoDB için Azure Cosmos DB API'si ile iletişim kuracaksınız. Ayrıca, Azure Cosmos DB kapasite modeline özgü veritabanı kaynaklarını oluşturmanıza ve almanıza yardımcı olmak için tasarlanmış MongoDB uzantısı komutlarını kullanacaksınız.

Önkoşullar

Önkoşul denetimi

  • Terminalde veya komut penceresinde komutunu çalıştırarak python --version Python'ın son sürümüne sahip olup olmadığınızı denetleyin.
  • Uygun Azure komut satırı araçlarının yüklü olup olmadığını denetlemek için (Azure CLI) veya Get-Module -ListAvailable Az* (Azure PowerShell) komutunu çalıştırın az --version .

Ayarlama

Bu bölümde, Azure Cosmos DB hesabı oluşturma ve MongoDB npm paketini kullanan bir proje ayarlama adımlarında size yol gösterilir.

Azure Cosmos DB hesabı oluşturma

Bu hızlı başlangıçta MongoDB API'sini kullanarak tek bir Azure Cosmos DB hesabı oluşturulacaktır.

  1. accountName, resourceGroupName ve location için kabuk değişkenleri oluşturun.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Henüz yapmadıysanız komutunu kullanarak az login Azure CLI'da oturum açın.

  3. az group create Aboneliğinizde yeni bir kaynak grubu oluşturmak için komutunu kullanın.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. az cosmosdb create MongoDB için varsayılan ayarlarla yeni bir Azure Cosmos DB hesabı oluşturmak için komutunu kullanın.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --kind MongoDB

MongoDB bağlantı dizesini alma

  1. Komutuyla hesabın bağlantı dizesi listesinden MongoDB bağlantı dizesi API'sini az cosmosdb keys list bulun.

    az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. BİRİnCİl ANAHTAR değerlerini kaydedin. Bu kimlik bilgilerini daha sonra kullanacaksınız.

Yeni python uygulaması oluşturma

  1. Tercih ettiğiniz terminali kullanarak yeni bir boş klasör oluşturun ve dizini klasör olarak değiştirin.

    Dekont

    Yalnızca tamamlanmış kodu istiyorsanız, tam örneği içeren örnek kod parçacıkları depoyu indirin veya çatallayın ve kopyalayın. Azure Cloud Shell'deki depoyu da git clone kullanarak bu hızlı başlangıçta gösterilen adımları izleyebilirsiniz.

  2. PyMongo ve python-dotenv paketlerini listeleyen bir requirements.txt dosyası oluşturun.

    # requirements.txt
pymongo
python-dotenv

  3. Sanal bir ortam oluşturun ve paketleri yükleyin.

    # py -3 uses the global python interpreter. You can also use python3 -m venv .venv.
py -3 -m venv .venv
source .venv/Scripts/activate   
pip install -r requirements.txt

Ortam değişkenlerini yapılandırma

Kodunuzda CONNECTION STRING değerlerini kullanmak için bu değeri uygulamayı çalıştıran yerel ortamda ayarlayın. Ortam değişkenini ayarlamak için tercih ettiğiniz terminali kullanarak aşağıdaki komutları çalıştırın:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Nesne modeli

Şimdi MongoDB için API'deki kaynak hiyerarşisine ve bu kaynakları oluşturmak ve bunlara erişmek için kullanılan nesne modeline göz atalım. Azure Cosmos DB, hesaplar, veritabanları, koleksiyonlar ve belgelerden oluşan bir hiyerarşide kaynaklar oluşturur.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Her kaynak türü bir Python sınıfıyla temsil edilir. En yaygın sınıflar şunlardır:

  • MongoClient - PyMongo ile çalışırken ilk adım, MongoDB için Azure Cosmos DB API'sine bağlanmak üzere bir MongoClient oluşturmaktır. İstemci nesnesi, hizmette istekleri yapılandırmak ve yürütmek için kullanılır.

  • Veritabanı - MongoDB için Azure Cosmos DB API'si bir veya daha fazla bağımsız veritabanını destekleyebilir.

  • Koleksiyon - Bir veritabanı bir veya daha fazla koleksiyon içerebilir. Koleksiyon, MongoDB'de depolanan bir belge grubudur ve kabaca ilişkisel veritabanındaki bir tablonun eşdeğeri olarak düşünülebilir.

  • Belge - Belge, anahtar-değer çiftleri kümesidir. Belgelerin dinamik şeması vardır. Dinamik şema, aynı koleksiyondaki belgelerin aynı alan veya yapı kümesine sahip olması gerekmeyecek anlamına gelir. Ayrıca bir koleksiyonun belgelerindeki ortak alanlar farklı veri türlerini barındırabilir.

Varlıkların hiyerarşisi hakkında daha fazla bilgi edinmek için Azure Cosmos DB kaynak modeli makalesine bakın.

Kod örnekleri

Bu makalede açıklanan örnek kod adlı bir koleksiyonla adlı adventureworksproductsbir veritabanı oluşturur. Koleksiyon products ad, kategori, miktar ve satış göstergesi gibi ürün ayrıntılarını içerecek şekilde tasarlanmıştır. Her ürün benzersiz bir tanımlayıcı da içerir. Örnek kodun tamamı konumundadır https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Aşağıdaki adımlar için veritabanı parçalama kullanmaz ve PyMongo sürücüsünü kullanan zaman uyumlu bir uygulama gösterir. Zaman uyumsuz uygulamalar için Motor sürücüsünü kullanın.

İstemcinin kimliğini doğrulama

  1. Proje dizininde bir run.py dosyası oluşturun. Düzenleyicinizde, PyMongo ve python-dotenv paketleri de dahil olmak üzere kullanacağınız paketlere başvurmak için require deyimleri ekleyin.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. Bir .env dosyasında tanımlanan ortam değişkeninden bağlantı bilgilerini alın.

    load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")

  3. Kodda kullanacağınız sabitleri tanımlayın.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

MongoDB için Azure Cosmos DB API'sine Bağlan

MongoDB için Azure Cosmos DB kaynağınıza bağlanmak için MongoClient nesnesini kullanın. connect yöntemi veritabanına bir başvuru döndürür.

client = pymongo.MongoClient(CONNECTION_STRING)

Veritabanı alma

Veritabanının list_database_names yöntemiyle var olup olmadığını denetleyin. Veritabanı yoksa, veritabanı uzantısını oluştur komutunu kullanarak belirtilen sağlanan aktarım hızıyla oluşturun.

# Create database if it doesn't exist
db = client[DB_NAME]
if DB_NAME not in client.list_database_names():
    # Create a database with 400 RU throughput that can be shared across
    # the DB's collections
    db.command({"customAction": "CreateDatabase", "offerThroughput": 400})
    print("Created db '{}' with shared throughput.\n".format(DB_NAME))
else:
    print("Using database: '{}'.\n".format(DB_NAME))

Koleksiyon alma

Koleksiyonun list_collection_names yöntemiyle var olup olmadığını denetleyin. Koleksiyon yoksa, oluşturmak için create collection extension komutunu kullanın.

# Create collection if it doesn't exist
collection = db[COLLECTION_NAME]
if COLLECTION_NAME not in db.list_collection_names():
    # Creates a unsharded collection that uses the DBs shared throughput
    db.command(
        {"customAction": "CreateCollection", "collection": COLLECTION_NAME}
    )
    print("Created collection '{}'.\n".format(COLLECTION_NAME))
else:
    print("Using collection: '{}'.\n".format(COLLECTION_NAME))

Dizin oluşturma

Güncelleştirme koleksiyonu uzantısı komutunu kullanarak bir dizin oluşturun. Dizini koleksiyon uzantısı oluştur komutunda da ayarlayabilirsiniz. Daha sonra ürün adında imleç sınıfı sıralama yöntemiyle sıralama yapmak için bu örnekte dizini name özelliğine ayarlayın.

indexes = [
    {"key": {"_id": 1}, "name": "_id_1"},
    {"key": {"name": 2}, "name": "_id_2"},
]
db.command(
    {
        "customAction": "UpdateCollection",
        "collection": COLLECTION_NAME,
        "indexes": indexes,
    }
)
print("Indexes are: {}\n".format(sorted(collection.index_information())))

Belge oluşturma

Veritabanının ürün özelliklerine adventureworks sahip bir belge oluşturun:

  • Kategori özelliği. Bu özellik mantıksal bölüm anahtarı olarak kullanılabilir.
  • Ad özelliği.
  • Stok miktarı özelliği.
  • Ürünün satışta olup olmadığını gösteren bir satış özelliği.
"""Create new document and upsert (create or replace) to collection"""
product = {
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard-{}".format(randint(50, 5000)),
    "quantity": 1,
    "sale": False,
}
result = collection.update_one(
    {"name": product["name"]}, {"$set": product}, upsert=True
)
print("Upserted document with _id {}\n".format(result.upserted_id))

Koleksiyon düzeyi işlemini update_one çağırarak koleksiyonda bir belge oluşturun. Bu örnekte, yeni bir belge oluşturmak yerine upsert ekleyeceksiniz. Ürün adı rastgele olduğundan bu örnekte Upsert gerekli değildir. Ancak, kodu birden çok kez çalıştırmanız ve ürün adının aynı olması durumunda upsert uygulamak iyi bir uygulamadır.

İşlemin update_one sonucu, sonraki işlemlerde kullanabileceğiniz alan değerini içerir _id . _id özelliği otomatik olarak oluşturuldu.

Belge alma

Belge almak için find_one yöntemini kullanın.

doc = collection.find_one({"_id": result.upserted_id})
print("Found a document with _id {}: {}\n".format(result.upserted_id, doc))

Azure Cosmos DB'de hem benzersiz tanımlayıcıyı (_id) hem de bölüm anahtarını kullanarak daha ucuz bir nokta okuma işlemi gerçekleştirebilirsiniz.

Belgeleri sorgulama

Belge ekledikten sonra, belirli bir filtreyle eşleşen tüm belgeleri almak için bir sorgu çalıştırabilirsiniz. Bu örnek, belirli bir kategoriyle eşleşen tüm belgeleri bulur: gear-surf-surfboards. Sorgu tanımlandıktan sonra bir sonuç almak için çağrısı Collection.find yapın ve sıralamayı kullanın.Cursor

"""Query for documents in the collection"""
print("Products with category 'gear-surf-surfboards':\n")
allProductsQuery = {"category": "gear-surf-surfboards"}
for doc in collection.find(allProductsQuery).sort(
    "name", pymongo.ASCENDING
):
    print("Found a product with _id {}: {}\n".format(doc["_id"], doc))

Sorun Giderme:

  • gibi The index path corresponding to the specified order-by item is excluded.bir hata alırsanız dizini oluşturduğunuzdan emin olun.

Kodu çalıştırma

Bu uygulama MongoDB veritabanı ve koleksiyonu için bir API oluşturur, bir belge oluşturur ve ardından tam olarak aynı belgeyi okur. Son olarak, örnek belirtilen bir ürün kategorisiyle eşleşen belgeleri döndüren bir sorgu verir. Her adımda örnek, konsola gerçekleştirdiği adımlarla ilgili bilgiler gönderir.

Uygulamayı çalıştırmak için bir terminal kullanarak uygulama dizinine gidin ve uygulamayı çalıştırın.

python run.py

Uygulamanın çıkışı şu örneğe benzer olmalıdır:


Created db 'adventureworks' with shared throughput.

Created collection 'products'.

Indexes are: ['_id_', 'name_1']

Upserted document with _id <ID>

Found a document with _id <ID>:
{'_id': <ID>,
'category': 'gear-surf-surfboards',
'name': 'Yamba Surfboard-50',
'quantity': 1,
'sale': False}

Products with category 'gear-surf-surfboards':

Found a product with _id <ID>:
{'_id': ObjectId('<ID>'),
'name': 'Yamba Surfboard-386',
'category': 'gear-surf-surfboards',
'quantity': 1,
'sale': False}

Kaynakları temizleme

NoSQL için Azure Cosmos DB hesabına artık ihtiyacınız kalmadığında ilgili kaynak grubunu silebilirsiniz.

az group delete Kaynak grubunu silmek için komutunu kullanın.

az group delete --name $resourceGroupName