Criar documentos

Concluído

Para criar um novo item, devemos primeiro criar uma nova variável no código C# do tipo Product .

Product saddle = new()
{
    id = "027D0B9A-F9D9-4C96-8213-C8546C4AAE71",
    categoryId = "26C74104-40BC-4541-8EF5-9892F7F03D72",
    name = "LL Road Seat/Saddle",
    price = 27.12d,
    tags = new string[] 
    {
        "brown",
        "weathered"
    }
};

Vamos inferir que já existe uma variável do tipo Microsoft.Azure.Cosmos. Contêiner chamado contêiner.

Podemos invocar de forma assíncrona o método CreateItemAsync<> passando o tipo Product e a nova variável de item para o construtor.

await container.CreateItemAsync<Product>(saddle);

Essa invocação do método cria o novo item, mas não tem metadados sobre o resultado da operação. Como alternativa, você pode armazenar o resultado da operação em uma variável do tipo ItemResponse<>.

ItemResponse<Product> response = await container.CreateItemAsync<Product>(saddle);

HttpStatusCode status = response.StatusCode;
double requestUnits = response.RequestCharge;

Product item = response.Resource;

Se você estiver usando um bloco try-catch, poderá manipular o tipo CosmosException , que inclui uma propriedade StatusCode para valores de código de status HTTP. Há alguns códigos de status HTTP comuns que você deve considerar no código do aplicativo:

Código	Título	Razão
400	Pedido Incorreto	Algo estava errado com o item no corpo do pedido
403	Proibido	Contentor estava provavelmente cheio
409	Conflito	O item no contêiner provavelmente já tinha um id correspondente
413	EntidadeDoPedidoDemasiadoGrande	O item excede o tamanho máximo da entidade
429	Demasiadas Solicitações	A solicitação atual excede o máximo de RU/s provisionado para o contêiner

No exemplo a seguir, lidamos com um cenário de conflito em que o item já existe no contêiner e recorremos a um bloco geral de tratamento de exceções para outros cenários:

try
{
    await container.CreateItemAsync<Product>(saddle);
}
catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
{
    // Add logic to handle conflicting ids
}
catch(CosmosException ex) 
{
    // Add general exception handling logic
}

Para criar um novo item em um contêiner do Azure Cosmos DB, primeiro você precisa criar uma instância do seu modelo de item. Em Python, esse processo pode ser alcançado definindo uma instância da classe Product .

saddle = Product(
        internal_id="2a7816bf-9a3c-4f33-b7d7-84efb3923538",
        name="Road Warrior Saddle",
        category_id="26C74104-40BC-4541-8EF5-9892F7F03D72",
        price=65.15,
        tags=["black", "cushioned", "leather"]
    ).to_dict()

Lembre-se de que a classe Product tem um to_dict método que converte a instância em um dicionário. Essa classe também mapeia a internal_id propriedade para a id propriedade, que o Azure Cosmos DB exige.

Vamos supor que já exista uma variável do tipo azure.cosmos.Containerchamada container.

Você pode usar o método create_item para criar um novo item no contêiner.

container.create_item(body=saddle)

Essa invocação do método cria o novo item, mas não fornece metadados sobre o resultado da operação. Como alternativa, você pode capturar a resposta da operação em uma variável. O get_response_headers() método recupera metadados sobre a operação, como a cobrança de solicitação e o valor ETag do item criado, o que permite cenários de simultaneidade otimistas.

response = container.create_item(body=saddle)
# Get response headers
headers = response.get_response_headers()

# Retrieve the created item
item = response

# Extract metadata from headers
request_charge = headers.get('x-ms-request-charge')
etag = headers.get('etag')

# Output the metadata
print(f"Request Charge: {request_charge}")
print(f"etag: {etag}")

print(f"Item created: {item}")

• x-ms-request-charge: As unidades de solicitação (RUs) consumidas pela operação.
• etag: Um valor exclusivo que representa a versão do item.

Tratamento de exceções

O SDK do Python gera exceções para vários cenários. Você pode lidar com essas exceções usando um try-except bloco. A exceção CosmosHttpResponseError inclui informações úteis, como o código de status HTTP. Alguns códigos de status HTTP comuns que você pode encontrar incluem:

Código	Título	Razão
400	Pedido Incorreto	Algo estava errado com o item no corpo do pedido
403	Proibido	Contentor estava provavelmente cheio
409	Conflito	O item no contêiner provavelmente já tinha um id correspondente
413	EntidadeDoPedidoDemasiadoGrande	O item excede o tamanho máximo da entidade
429	Demasiadas Solicitações	A solicitação atual excede o máximo de RU/s provisionado para o contêiner

Veja um exemplo de como lidar com essas exceções:

from azure.cosmos.exceptions import CosmosHttpResponseError

try:
    container.create_item(body=saddle)
except CosmosHttpResponseError as ex:
    if ex.status_code == 409:  # Conflict
        print("Conflict: Item with the same id already exists.")
    elif ex.status_code == 429:  # Too Many Requests
        print("Too many requests: Reduce request rate or increase RU/s provisioned.")
    elif ex.status_code == 400:  # Bad Request
        print("Bad request: Check the structure of the item being sent.")
    else:
        print(f"HTTP error occurred: Status code {ex.status_code}, message: {ex.message}")
except Exception as ex:
    print(f"An unexpected error occurred: {ex}")

Para criar um novo item, primeiro você precisa definir um objeto que represente seus dados.

Definir o item

Defina o item em JavaScript como um objeto com todas as propriedades necessárias. Por exemplo, veja como você pode definir um item de produto:

const saddle = new Product(
    "027D0B9A-F9D9-4C96-8213-C8546C4AAE72", // internalId
    "LL Road Seat/Saddle", // name
    "26C74104-40BC-4541-8EF5-9892F7F03D72", // categoryId
    27.12, // price
    ["brown", "weathered"] // tags
);

Este objeto tem as seguintes propriedades:

• internalId: Um identificador exclusivo para o item.
• categoryId: Uma propriedade que corresponde ao caminho da chave de partição do contêiner.
• Outras propriedades, como name, price, e tags, que descrevem o item.

Lembre-se de que a classe Product tem um toJSON() método que converte o objeto em uma cadeia de caracteres JSON. Essa classe também mapeia a internalId propriedade para a id propriedade, que o Azure Cosmos DB exige.

Criar o item

Suponha que já exista uma variável do tipo Containerchamada container. Você pode usar o método items.create para criar o item.

const { resource: item } = await container.items.create(saddle);

Esse método envia uma solicitação para criar o item no contêiner do Azure Cosmos DB.

Recuperar metadados

A resposta do items.create método inclui cabeçalhos que fornecem metadados úteis sobre a operação, como a cobrança de solicitação e o valor ETag, o que permite cenários de simultaneidade otimistas.

const { resource: item, headers } = await container.items.create(saddle);

const requestCharge = headers["x-ms-request-charge"];
const etag = headers.etag;

console.log(`Request Charge: ${requestCharge}`);
console.log(`etag: ${etag}`);
console.log("Item created:", item);

• x-ms-request-charge: As unidades de solicitação (RUs) consumidas pela operação.
• etag: Um valor exclusivo que representa a versão do item.

Manipular erros

Ao criar um item, podem ocorrer erros, como conflitos ou solicitações inválidas. Use um try-catch bloco para lidar com esses erros. Alguns códigos de status HTTP comuns que você pode encontrar incluem:

Código	Título	Razão
400	Pedido Incorreto	Algo estava errado com o item no corpo do pedido
403	Proibido	Contentor estava provavelmente cheio
409	Conflito	O item no contêiner provavelmente já tinha um id correspondente
413	EntidadeDoPedidoDemasiadoGrande	O item excede o tamanho máximo da entidade
429	Demasiadas Solicitações	A solicitação atual excede o máximo de RU/s provisionado para o contêiner

try {
    const { resource: item, headers } = await container.items.create(saddle);
    console.log("Item created:", item);
} catch (error) {
    if (error.code === 409) {
        console.log(`Conflict: Item with the same id (${saddle.id}) already exists.`);
    } else if (error.code === 429) {
        console.log("Too many requests: Reduce request rate or increase RU/s provisioned.");
    } else if (error.code === 400) {
        console.log("Bad request: Check the structure of the item being sent.");
    } else {
        console.log(`An unexpected error occurred: ${error.message}`);
    }
}

Essa implementação garante que você possa criar itens, recuperar metadados para diagnóstico e lidar com erros normalmente.