Criar um contêiner no Azure Cosmos DB for NoSQL usando o Python

APLICA-SE A: NoSQL

Contêineres nos conjuntos de armazenamento de itens do Azure Cosmos DB. Antes de poder criar, consultar ou gerenciar itens, você deve criar um contêiner.

Nomear um contêiner

No Azure Cosmos DB, um contêiner é análogo a uma tabela em um banco de dados relacional. Quando você cria um contêiner, o nome do contêiner forma um segmento do URI usado para acessar o recurso de contêiner e todos os itens filho.

Após criado, o URI para um contêiner ficará neste formato:

https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/colls/<container-name>

Criar um contêiner

Para criar um contêiner, chame um dos seguintes métodos:

• CreateContainerAsync
• CreateContainerIfNotExistsAsync
• Criar um contêiner de maneira assíncrona

Criar um contêiner

O exemplo a seguir cria um contêiner com o método DatabaseProxy.create_container. Quando já existe um contêiner com o mesmo nome, esse método gera uma exceção.

try:
    partition_key_path = PartitionKey(path="/categoryId")
    container = database.create_container(
        id=CONTAINER_ID,
        partition_key=partition_key_path,
        offer_throughput=400,
    )
    print(f"Container created: {container.id}")

except CosmosResourceExistsError:
    print("Container already exists.")

Criar um contêiner se ele ainda não existe

O exemplo a seguir cria um contêiner com o método DatabaseProxy.create_container_if_not_exists. Em comparação com o método de criação anterior, esse método não gera uma exceção quando o banco de dados já existe. Esse método é útil para evitar erros se você executar o mesmo código várias vezes.

try:
    partition_key_path = PartitionKey(path="/categoryId")
    container = database.create_container_if_not_exists(
        id=CONTAINER_ID,
        partition_key=partition_key_path,
        offer_throughput=400,
    )
    print(f"Container created or returned: {container.id}")

except CosmosHttpResponseError:
    print("Request to the Azure Cosmos database service failed.")

Criar um contêiner de maneira assíncrona

Também é possível criar um banco de dados de maneira assíncrona usando métodos e objetos semelhantes no namespace azure.cosmos.aio. Por exemplo, use o método DatabaseProxy.create_database ou o método CosmoClient.create_database_if_not_exists.

Trabalhar de maneira assíncrona é útil quando você deseja executar várias operações em paralelo. Para obter mais informações, confira Usando o cliente assíncrono.

Análise da resposta

Nos exemplos acima, a resposta das solicitações é ContainerProxy, que é uma interface para interagir com um contêiner de banco de dados. No proxy, é possível acessar métodos para executar operações no contêiner.

O exemplo a seguir mostra o método create_container_if_not_exists retornando um objeto de contêiner.

partition_key_path = PartitionKey(path="/categoryId")
container = database.create_container_if_not_exists(
    id=CONTAINER_ID,
    partition_key=partition_key_path,
    offer_throughput=400,
)
for doc in container.read_all_items(max_item_count=10):
    print(f'Doc id: {doc["id"]}')

Próximas etapas

Agora que você criou um contêiner, use o próximo guia para criar itens.