Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para Apache Cassandra para Python

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

Introdução à biblioteca de cliente do Azure Cosmos DB para Apache Cassandra para Python para armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de cliente 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 não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

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

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

• Python 3.12 ou posterior

Preparação

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, obtenção de suas credenciais e, em seguida, preparação do ambiente de desenvolvimento.

Criar uma conta

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

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 espaço de chave chamado 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 Azure Cosmos DB na barra de pesquisa global.

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

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

5. Selecione Conta de banco de dados de unidade de solicitação (RU) para o tipo de conta.

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

   	Valor
   Tipo de carga de trabalho	Aprendizagem
   Subscrição	Selecione sua assinatura do Azure
   Grupo de Recursos	Criar um novo grupo de recursos ou selecionar um grupo de recursos existente
   Nome da Conta	Forneça um nome globalmente exclusivo
   Zonas de Disponibilidade	Desativar
   Localização	Selecione uma região do Azure suportada para a sua subscrição

   Sugestão

   Você pode deixar quaisquer opções não especificadas para seus 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 o nível gratuito para minimizar seus custos.

7. No painel Rever + criar, aguarde até que a validação da sua conta conclua com sucesso e, em seguida, selecione Criar.

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

9. Quando a implantação estiver concluída, selecione Ir para o recurso para navegar até a nova API para a conta 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:

    	Valor
    Keyspace	Criar novo
    Nome do espaço de chave	cosmicworks
    Nome da tabela	product
    Esquema da tabela	(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))

    Sugestão

    Você pode deixar quaisquer opções não especificadas para seus valores padrão.

Obter credenciais

Agora, obtenha a palavra-passe da biblioteca do cliente para usar e criar uma conexão com a conta criada recentemente.

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. Registe 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ê usa 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. Registe o valor da propriedade primaryMasterKey a partir da saída dos comandos anteriores. O valor dessa propriedade é a senha que você usa 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. Registe o valor do campo PONTO DE CONTACTO nesta página. O valor dessa propriedade é o ponto de contato que você usa 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ê usa posteriormente neste guia para se conectar à conta com a biblioteca.

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

Preparar o ambiente de desenvolvimento

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

1. Comece em um diretório vazio.

2. Importe o cassandra-driver pacote do Python Package Index (PyPI).

   pip install cassandra-driver
   

3. Crie o arquivo app.py .

Modelo de objeto

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

Exemplos de código

• Autenticar cliente
• Dados Upsert
• Ler dados
• Consultar dados

Autenticar cliente

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

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

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 username, passworde contactPoint.

   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, desativando a verificação de nome de 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 credencial e configuração 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")
   

Advertência

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

Atualizar ou inserir dados

Em seguida, atualize novos dados para uma tabela. A atualização 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 Cassandra Query Language (CQL) 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 do produto criado anteriormente neste guia.

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

3. Use a execute função para executar a consulta armazenada na 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 função one para obter o resultado único esperado. Armazene esse ú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 string 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. Utilize um for loop para iterar pelos resultados da consulta.

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

Execute o código

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

python app.py

Limpeza de recursos

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

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 que você criou 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óximo passo

Visão geral do Azure Cosmos DB para Apache Cassandra