Rychlý start: Klientská knihovna Azure Cosmos DB for Apache Cassandra pro Python

• Python
• Node.js
• C#
• Java
• Pokračovat

Začínáme s klientskou knihovnou Azure Cosmos DB for Apache Cassandra pro Python pro ukládání, správu a dotazování nestrukturovaných dat Postupujte podle kroků v tomto průvodci a vytvořte nový účet, nainstalujte klientskou knihovnu Pythonu, připojte se k účtu, proveďte běžné operace a dotazujte se na konečná ukázková data.

Referenční dokumentace API | Zdrojový kód knihovny | Balíček (PyPI)

Požadavky

• Předplatné Azure

  • Pokud nemáte předplatné Azure, vytvořte si bezplatný účet před zahájením.

• Nejnovější verze Azure CLI v Azure Cloud Shellu

  • Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, přihlaste se k Azure CLI pomocí az login příkazu.

• Python 3.12 nebo novější

Instalace

Nejprve pro tuto příručku nastavte účet a vývojové prostředí. Tato část vás provede procesem vytvoření účtu, získáním jeho přihlašovacích údajů a následnou přípravou vývojového prostředí.

Vytvoření účtu

Začněte vytvořením rozhraní API pro účet Apache Cassandra. Po vytvoření účtu vytvořte klíčový prostor a tabulkové zdroje.

Azure CLI

1. Pokud ještě nemáte cílovou skupinu prostředků, použijte az group create příkaz k vytvoření nové skupiny prostředků ve vašem předplatném.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. az cosmosdb create Pomocí příkazu vytvořte nový účet Azure Cosmos DB pro Apache Cassandra s výchozím nastavením.

   az cosmosdb create \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --locations "regionName=<location>" \
       --capabilities "EnableCassandra"
   

3. Vytvořte nový keyspace pojmenovaný az cosmosdb cassandra keyspace createcosmicworks.

   az cosmosdb cassandra keyspace create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --name "cosmicworks"
   

4. Vytvořte nový objekt JSON, který bude reprezentovat schéma pomocí příkazu Bash s více řádky. Potom pomocí az cosmosdb cassandra table create příkazu vytvořte novou tabulku s názvem products.

   schemaJson=$(cat <<EOF
   {
     "columns": [
       {
         "name": "id",
         "type": "text"
       },
       {
         "name": "name",
         "type": "text"
       },
       {
         "name": "category",
         "type": "text"
       },
       {
         "name": "quantity",
         "type": "int"
       },
       {
         "name": "price",
         "type": "decimal"
       },
       {
         "name": "clearance",
         "type": "boolean"
       }
     ],
     "partitionKeys": [
       {
         "name": "id"
       }
     ]
   }
   EOF
   )
   

   az cosmosdb cassandra table create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --keyspace-name "cosmicworks" \
       --name "product" \
       --schema "$schemaJson"
   

Azure Portal

1. Přihlaste se k webu Azure Portal (https://portal.azure.com).

2. Do globálního panelu hledání zadejte Azure Cosmos DB .

3. V rámci služeb vyberte Azure Cosmos DB.

4. V podokně Azure Cosmos DB vyberte Vytvořit a potom Azure Cosmos DB for Apache Cassandra na kartě Ostatní.

5. Jako typ účtu vyberte účet databáze jednotky žádosti (RU ).

6. V podokně Základy nakonfigurujte následující možnosti a pak vyberte Zkontrolovat a vytvořit:

   	Hodnota
   Typ úlohy	Vzdělávání
   Předplatné	Výběr předplatného Azure
   Skupina prostředků	Vytvoření nové skupiny prostředků nebo výběr existující skupiny prostředků
   Název účtu	Zadejte globálně jedinečný název.
   Zóny dostupnosti	Zakázat
   Umístění	Vyberte podporovanou oblast Azure pro vaše předplatné.

   Návod

   U výchozích hodnot můžete ponechat všechny nezadané možnosti. Můžete také nakonfigurovat účet tak, aby omezil celkovou propustnost účtu na 1 000 jednotek žádostí za sekundu (RU/s), nebo povolit úroveň Free, aby se minimalizovaly náklady.

7. V podokně Zkontrolovat a vytvořit počkejte na úspěšné ověření účtu a pak vyberte Vytvořit.

8. Portál automaticky přejde do podokna Nasazení . Počkejte, až se nasazení dokončí.

9. Po dokončení nasazení vyberte Přejít k prostředku a přejděte do nového rozhraní API pro účet Apache Cassandra.

10. V nabídce prostředků vyberte možnost Průzkumník dat .

11. V Průzkumníku dat vyberte + Nová tabulka.

12. V dialogovém okně Přidat tabulku nakonfigurujte následující možnosti a pak vyberte OK:

    	Hodnota
    Keyspace	Create new
    Název prostoru klíčů	cosmicworks
    Název tabulky	product
    Schéma tabulky	(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))

    Návod

    U výchozích hodnot můžete ponechat všechny nezadané možnosti.

Získání přihlašovacích údajů

Teď získejte heslo pro klientskou knihovnu, které se má použít k vytvoření připojení k nedávno vytvořenému účtu.

Azure CLI

1. Slouží az cosmosdb show k získání kontaktního bodu a uživatelského jména pro účet.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{username:name,contactPoint:documentEndpoint}"
   

2. Poznamenejte si hodnotu contactPoint a username vlastnosti z výstupu předchozích příkazů. Hodnoty těchto vlastností jsou kontaktní bod a uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Slouží az cosmosdb keys list k získání klíčů pro účet.

   az cosmosdb keys list \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --type "keys"
   

4. Poznamenejte si hodnotu primaryMasterKey vlastnosti z výstupu předchozích příkazů. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Azure Portal

1. V nabídce prostředků pro účet vyberte možnost Připojovací řetězce v části Nastavení .

2. Poznamenejte si hodnotu pole KONTAKTNÍ BOD na této stránce. Hodnota této vlastnosti je kontaktní bod , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Poznamenejte si hodnotu pole USERNAME na této stránce. Hodnota této vlastnosti je uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

4. Zveřejnit a zaznamenat hodnotu pole PRIMÁRNÍ HESLO na této stránce. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Příprava vývojového prostředí

Potom nakonfigurujte vývojové prostředí s novým projektem a klientskou knihovnou. Tento krok je posledním požadovaným předpokladem před přechodem na zbytek této příručky.

1. Začněte v prázdném adresáři.

2. cassandra-driver Importujte balíček z indexu balíčků Pythonu (PyPI).

   pip install cassandra-driver
   

3. Vytvořte soubor app.py.

Objektový model

	Popis
Cluster	Představuje konkrétní připojení ke clusteru.

Příklady kódu

• Ověření klienta
• Provést operaci Upsert (aktualizace nebo vložení) na data
• Čtení dat
• Dotazování dat

Ověření klienta

Začněte ověřením klienta pomocí přihlašovacích údajů shromážděných dříve v této příručce.

1. Otevřete soubor app.py v integrovaném vývojovém prostředí (IDE).

2. Importujte z cassandra-driver modulu následující typy:

   • cassandra.cluster.Cluster
   • cassandra.auth.PlainTextAuthProvider

   from cassandra.cluster import Cluster
   from cassandra.auth import PlainTextAuthProvider
   

3. Importujte z ssl modulu následující typy:

   • ssl.PROTOCOL_TLS_CLIENT
   • ssl.SSLContext
   • ssl.CERT_NONE

   from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
   

4. Vytvořte řetězcové proměnné pro přihlašovací údaje shromážděné dříve v této příručce. Pojmenujte proměnné username, passworda contactPoint.

   username = "<username>"
   password = "<password>"
   contactPoint = "<contact-point>"
   

5. SSLContext Nakonfigurujte tak, že vytvoříte novou proměnnou s názvem ssl_context, nastavíte protokol na PROTOCOL_TLS_CLIENT, zakážete kontrolu názvu hostitele a nastavíte režim ověřování na CERT_NONE.

   ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
   ssl_context.check_hostname = False
   ssl_context.verify_mode = CERT_NONE
   

6. Vytvořte nový PlainTextAuthProvider objekt s přihlašovacími údaji zadanými v předchozích krocích. Uložte výsledek do proměnné s názvem auth_provider.

   auth_provider = PlainTextAuthProvider(username=username, password=password)
   

7. Vytvořte Cluster objekt pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích. Uložte výsledek do proměnné s názvem cluster.

   cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
   

8. Připojte se ke clusteru.

   session = cluster.connect("cosmicworks")
   

Výstraha

Úplné ověření protokolu TLS (Transport Layer Security) je v tomto průvodci zakázané, aby se zjednodušilo ověřování. Pro produkční nasazení plně povolte ověřování.

Vložit nebo aktualizovat data

V dalším kroku přepište nová data do tabulky. Přenesení zajistí, že se data vytvoří nebo nahradí odpovídajícím způsobem v závislosti na tom, jestli stejná data již v tabulce existují.

1. Vytvořte novou řetězcovou proměnnou s názvem insertQuery dotazu Cassandra Query Language (CQL) pro vložení nového řádku.

   insertQuery = """
   INSERT INTO
       product (id, name, category, quantity, price, clearance)
   VALUES
       (%(id)s, %(name)s, %(category)s, %(quantity)s, %(price)s, %(clearance)s)
   """
   

2. Vytvořte nový objekt s různými vlastnostmi nového produktu a uložte ho do proměnné s názvem params.

   params = {
       "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       "name": "Yamba Surfboard",
       "category": "gear-surf-surfboards",
       "quantity": 12,
       "price": 850.00,
       "clearance": False
   }
   

3. execute Pomocí funkce spusťte dotaz se zadanými parametry.

   session.execute(insertQuery, params)
   

Čtení dat

Potom načtěte data, která byla dříve převedena do tabulky.

1. Vytvořte novou řetězcovou proměnnou pojmenovanou readQuery s dotazem CQL, který odpovídá položkám se stejným polem id.

   readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
   

2. Vytvořte řetězcovou proměnnou s názvem id se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

   id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   

3. Pomocí funkce execute spusťte dotaz uložený v readQuery, přičemž proměnnou id použijte jako argument. Uložte výsledek do proměnné s názvem readResults.

   readResults = session.execute(readQuery, (id,))
   

4. one Použijte funkci, která získá očekávaný jediný výsledek. Uložte tento jediný výsledek do proměnné s názvem matchedProduct.

   matchedProduct = readResults.one()
   

Dotaz k datům

Nakonec pomocí dotazu najděte všechna data, která odpovídají určitému filtru v tabulce.

1. Vytvořte řetězcové proměnné pojmenované findQuery a category pomocí dotazu CQL a požadovaného parametru.

   findQuery = "SELECT * FROM product WHERE category = %s ALLOW FILTERING"
   category = "gear-surf-surfboards"
   

2. Pomocí dvou řetězcových proměnných a execute funkce můžete dotazovat více výsledků. Uložte výsledek tohoto dotazu do proměnné s názvem findResults.

   findResults = session.execute(findQuery, (category,))
   

3. for Pomocí smyčky iterujte výsledky dotazu.

   for row in findResults:
       # Do something here with each result
   

Spuštění kódu

Spusťte nově vytvořenou aplikaci pomocí terminálu v adresáři vaší aplikace.

python app.py

Vyčistěte zdroje

Pokud účet už nepotřebujete, odeberte ho z předplatného Azure odstraněním prostředku.

Azure CLI

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Azure Portal

1. Přejděte k existujícímu prostředku Azure Cosmos DB for Apache Cassandra , který jste vytvořili dříve v této příručce.

2. Na stránce zdroje vyberte na panelu nástrojů Odstranit.

3. Postupujte podle pokynů v potvrzovacím dialogovém okně.

Další krok

Přehled služby Azure Cosmos DB pro Apache Cassandra