Início Rápido: Biblioteca de Cliente do Azure Cosmos DB para Apache Cassandra em Python

• Python
• Node.js
• C#
• Java
• Vá

Introdução à biblioteca de clientes do Azure Cosmos DB for Apache Cassandra para Python armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de clientes do Python, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (PyPI)

Pré-requisitos

• Uma assinatura do Azure

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• A versão mais recente da CLI do Azure no Azure Cloud Shell.

  • Se você preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

• Python 3.12 ou posterior

Configurando

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtendo suas credenciais e, em seguida, preparando seu ambiente de desenvolvimento.

Criar uma conta

Comece criando uma conta da API para Apache Cassandra. Depois que a conta for criada, crie o keyspace e os recursos da tabela.

Azure CLI

1. Se você ainda não tiver um grupo de recursos de destino, use o az group create comando para criar um novo grupo de recursos em sua assinatura.

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

2. Use o az cosmosdb create comando para criar uma nova conta do Azure Cosmos DB para Apache Cassandra com configurações padrão.

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

3. Crie um novo keyspace com o nome az cosmosdb cassandra keyspace create usando cosmicworks.

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

4. Crie um novo objeto JSON para representar seu esquema usando um comando Bash de várias linhas. Em seguida, use o az cosmosdb cassandra table create comando para criar uma nova tabela chamada 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"
   

Portal do Azure

1. Entre no portal do Azure (https://portal.azure.com).

2. Insira o Azure Cosmos DB na barra de pesquisa global.

3. Em Serviços, selecione Azure Cosmos DB.

4. No painel do Azure Cosmos DB , selecione Criar e, em seguida, Azure Cosmos DB para Apache Cassandra na guia Outros .

5. Selecione conta de banco de dados Unidade de Solicitação (RU) como o tipo de conta.

6. No painel Noções básicas, configure as seguintes opções e, em seguida, escolha Revisar + criar:

   	Value
   Tipo de carga de trabalho	Aprendizado
   Subscription	Selecione sua Assinatura do Azure.
   Grupo de Recursos	Crie um novo grupo de recursos ou escolha um grupo de recursos existente
   Nome da Conta	Forneça um nome global exclusivo
   Zonas de disponibilidade	Desabilitar
   Localidade	Escolha uma região do Azure compatível com sua assinatura

   Dica

   Você pode deixar as opções não especificadas com os valores padrão. Você também pode configurar a conta para limitar a taxa de transferência total da conta a 1.000 unidades de solicitação por segundo (RU/s) ou habilitar a camada gratuita para minimizar seus custos.

7. No painel Revisar + criar , aguarde a conclusão bem-sucedida da validação da conta e escolha Criar.

8. O portal navega automaticamente para o painel Implantação. Aguarde até que a implantação seja concluída.

9. Depois que a implantação for concluída, selecione Ir para o recurso para navegar até a nova conta da API para Apache Cassandra.

10. No menu de recursos, selecione a opção Data Explorer .

11. No Data Explorer, selecione + Nova Tabela.

12. Na caixa de diálogo Adicionar Tabela , configure as seguintes opções e selecione OK:

    	Value
    Keyspace	Criar novo
    Nome do keyspace	cosmicworks
    Nome da tabela	product
    Esquema de tabela	(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))

    Dica

    Você pode deixar as opções não especificadas com os valores padrão.

Obter credenciais

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

Azure CLI

1. Use az cosmosdb show para obter o ponto de contato e o nome de usuário da conta.

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

2. Registre o valor das propriedades contactPoint e username da saída dos comandos anteriores. Os valores dessas propriedades são o ponto de contato e o nome de usuário que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

3. Use az cosmosdb keys list para obter as chaves da conta.

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

4. Registre o valor da propriedade primaryMasterKey da saída dos comandos anteriores. O valor dessa propriedade é a senha que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Portal do Azure

1. No menu de recursos da conta, selecione a opção Cadeias de conexão na seção Configurações .

2. Registre o valor do campo CONTACT POINT nesta página. O valor dessa propriedade é o ponto de contato que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

3. Registre o valor do campo USERNAME nesta página. O valor dessa propriedade é o nome de usuário que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

4. Exponha e registre o valor do campo PRIMARY PASSWORD nesta página. O valor dessa propriedade é a senha que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Prepare o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca de clientes. Esta etapa é o último pré-requisito necessário antes de passar para o restante deste guia.

1. Inicie em um diretório vazio.

2. Importe o cassandra-driver pacote do PyPI (Índice de Pacotes do Python).

   pip install cassandra-driver
   

3. Crie o arquivo app.py.

Modelo de objeto

	Description
Cluster	Representa uma conexão específica com um cluster

Exemplos de código

• Autenticar cliente
• Atualizar/inserir dados
• Ler dados
• Consultar dados

Autenticar cliente

Comece autenticando o cliente usando as credenciais coletadas anteriormente neste guia.

1. Abra o arquivo app.py em seu IDE (ambiente de desenvolvimento integrado).

2. Importe os seguintes tipos do cassandra-driver módulo:

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

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

3. Importe os seguintes tipos do ssl módulo:

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

   from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
   

4. Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis usernamee passwordcontactPoint.

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

5. Configure o SSLContext criando uma nova variável chamada ssl_context, definindo o protocolo como PROTOCOL_TLS_CLIENT, desabilitando a verificação do nome do host e definindo o modo de verificação como CERT_NONE.

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

6. Crie um novo PlainTextAuthProvider objeto com as credenciais especificadas nas etapas anteriores. Armazene o resultado em uma variável chamada auth_provider.

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

7. Crie um Cluster objeto usando as variáveis de configuração e credencial criadas nas etapas anteriores. Armazene o resultado em uma variável chamada cluster.

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

8. Conecte-se ao cluster.

   session = cluster.connect("cosmicworks")
   

Aviso

A validação completa da TLS (segurança da camada de transporte) está desabilitada neste guia para simplificar a autenticação. Para implantações de produção, habilite totalmente a validação.

Inserir ou atualizar dados

Em seguida, insira novos dados em uma tabela. O upserting garante que os dados sejam criados ou substituídos adequadamente, dependendo se os mesmos dados já existem na tabela.

1. Crie uma nova variável de cadeia de caracteres nomeada insertQuery com a consulta CQL (Cassandra Query Language) para inserir uma nova linha.

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

2. Crie um novo objeto com várias propriedades de um novo produto e armazene-o em uma variável chamada params.

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

3. Use a execute função para executar a consulta com os parâmetros especificados.

   session.execute(insertQuery, params)
   

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente na tabela.

1. Crie uma nova variável de cadeia de caracteres nomeada readQuery com uma consulta CQL que corresponda a itens com o mesmo id campo.

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

2. Crie uma variável de cadeia de caracteres nomeada id com o mesmo valor que o produto criado anteriormente neste guia.

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

3. Use a execute função para executar a consulta armazenada em readQuery passando a variável id como um argumento. Armazene o resultado em uma variável chamada readResults.

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

4. Use a one função para obter o resultado único esperado. Armazene este único resultado em uma variável chamada matchedProduct.

   matchedProduct = readResults.one()
   

Consultar dados

Por fim, use uma consulta para localizar todos os dados que correspondem a um filtro específico na tabela.

1. Crie variáveis de cadeia de caracteres nomeadas findQuery e category com a consulta CQL e o parâmetro necessário.

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

2. Use as duas variáveis de cadeia de caracteres e a execute função para consultar vários resultados. Armazene o resultado dessa consulta em uma variável chamada findResults.

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

3. Use um loop for para iterar sobre os resultados da consulta.

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

Executar o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

python app.py

Limpar os recursos

Quando você não precisar mais da conta, remova a conta de sua assinatura do Azure excluindo o recurso.

Azure CLI

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

Portal do Azure

1. Navegue até o recurso existente do Azure Cosmos DB para Apache Cassandra criado anteriormente neste guia.

2. Na página do recurso, selecione Excluir na barra de menus.

3. Siga as instruções na caixa de diálogo de confirmação.

Próxima etapa

Visão geral do Azure Cosmos DB para Apache Cassandra