Criar Coleção
A Create Collection operação cria uma nova coleção numa base de dados.
Nota
Estes artigos de referência da API mostram como criar recursos com a API do plano de dados do Azure Cosmos DB. Com a API do plano de dados, pode configurar opções básicas, como a política de indexação, chaves de partição da mesma forma que pode com os SDKs do Cosmos DB. Se precisar de suporte completo de funcionalidades para todos os recursos do Azure Cosmos DB, recomendamos que utilize o Fornecedor de Recursos do Cosmos DB.
Pedir
| Método | URI do pedido | Description |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | A {databaseaccount} é o nome da conta do Azure Cosmos DB criada na sua subscrição. {db-id} pode ser o ID ou o valor _rid da base de dados. |
Cabeçalhos
Veja Common Azure Cosmos DB REST request headers for headers that are used by all Azure Cosmos DB requests (Cabeçalhos de pedido REST do Azure Cosmos DB comuns para cabeçalhos que são utilizados por todos os pedidos do Azure Cosmos DB).
Ao construir a assinatura hash para o token de chave mestra, o ResourceType deve ser "colls". O ResourceId deve ser dbs/{db-id}, em que {db-id} pode ser o ID ou o valor _rid da base de dados.
| Propriedade | Necessário | Tipo | Description |
|---|---|---|---|
| x-ms-offer-throughput | Opcional | Número | O utilizador especificou o débito manual (RU/s) para a coleção expressa em unidades de 100 unidades de pedido por segundo. O mínimo é de 400 até 1000 000 (ou superior ao pedir um aumento de limite). Apenas um de ou x-ms-cosmos-offer-autopilot-settings tem de x-ms-offer-throughput ser especificado. Estes cabeçalhos não podem ser especificados em conjunto. |
| x-ms-cosmos-offer-autopilot-settings | Opcional | JSON | O utilizador especificou ru/s máximas de dimensionamento automático. O valor é um JSON com a propriedade maxThroughput. Por exemplo: {"maxThroughput": 4000}.Apenas um de ou x-ms-cosmos-offer-autopilot-settings tem de x-ms-offer-throughput ser especificado. Estes cabeçalhos não podem ser especificados em conjunto. Quando o dimensionamento automático é utilizado, é necessária uma definição partitionKey . |
| x-ms-offer-type | Opcional | String | Este é um cabeçalho legado para os níveis de desempenho predefinidos S1, S2 e S3 que foram descontinuados. Recomenda-se que utilize o débito manual ou de dimensionamento automático, conforme descrito acima. |
Corpo
| Propriedade | Necessário | Tipo | Description |
|---|---|---|---|
| id | Necessário | String | O nome exclusivo gerado pelo utilizador para a coleção. Não é possível ter duas coleções com os mesmos IDs. É uma cadeia que não pode ter mais de 255 carateres. |
| indexingPolicy | Opcional | Objeto | Este valor é utilizado para configurar a política de indexação. Por predefinição, a indexação é automática para todos os caminhos de documento na coleção. |
| partitionKey | Necessário | Objeto | Este valor é utilizado para configurar a chave de partição a ser utilizada para a criação de partições de dados em múltiplas partições. Para utilizar uma chave de partição grande, especifique a versão como 2 na propriedade partitionKey. Se a versão da API REST for 2018-12-31 ou superior, a coleção tem de incluir uma definição partitionKey . Em versões anteriores a 2018-12-31, uma coleção legada não particionada com débito manual pode ser criada ao omitir a definição partitionKey e garantir que o débito está entre 400 e 10 000 RU/s. Para obter o melhor desempenho e escalabilidade, recomenda-se que defina sempre uma chave de partição. Saiba como escolher uma boa chave de partição. |
Payload do corpo de exemplo
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
Resposta
Criar Coleção devolve a coleção criada como um corpo de resposta.
Cabeçalhos
Veja Common Azure Cosmos DB REST response headers for headers that are returned by all Azure Cosmos DB responses (Cabeçalhos de resposta REST do Azure Cosmos DB comuns para cabeçalhos devolvidos por todas as respostas do Azure Cosmos DB).
Códigos de estado
A tabela seguinte lista os códigos de estado comuns devolvidos por esta operação. Para obter uma lista completa dos códigos de estado, consulte Códigos de Estado HTTP.
| Código de estado de HTTP | Descrição |
|---|---|
| 201 Criado | A operação foi bem-sucedida. |
| 400 Pedido Incorreto | O corpo JSON é inválido. Verifique se faltam parênteses ou aspas curvas. |
| 409 Conflito | O ID fornecido para a nova coleção foi tomado por uma coleção existente. |
| 404 com um código de sub-estado de 1013 | A operação de criação da coleção ainda está em curso. |
Se encontrar uma exceção de tempo limite ao criar uma coleção, execute uma operação de leitura para validar se a coleção foi criada com êxito. A operação de leitura gera uma exceção até que a operação de criação da coleção seja bem-sucedida. Se a operação de leitura lançar uma exceção com o código de estado 404 e o código de sub-estado do 1013, significa que a operação de criação da coleção ainda está em curso. Repita a operação de leitura até obter códigos de estado 200 ou 201, estes códigos informam-no de que a coleção foi criada com êxito.
Corpo
| Propriedade | Descrição |
|---|---|
| id | É o nome exclusivo que identifica a nova coleção. |
| _rid | É uma propriedade gerada pelo sistema. O ID de recurso (_rid) é um identificador exclusivo que também é hierárquico, de acordo com pilha de recursos no modelo de recursos. É utilizado internamente para colocação e navegação do recurso de permissão. |
| _ts | É uma propriedade gerada pelo sistema. Especifica o último carimbo de data/hora atualizado do recurso. O valor é um carimbo de data/hora. |
| _self | É uma propriedade gerada pelo sistema. É o URI endereçável exclusivo para o recurso. |
| _etag | É uma propriedade gerada pelo sistema que representa a etag de recursos necessária para o controlo de simultaneidade otimista. |
| _doc | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de documentos. |
| _sprocs | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de procedimentos armazenados (sprocs). |
| _triggers | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de acionadores. |
| _udfs | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de funções definidas pelo utilizador (udfs). |
| _conflicts | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de conflitos. Durante uma operação num recurso numa coleção, se ocorrer um conflito, os utilizadores podem inspecionar os recursos em conflito ao efetuar um GET no caminho do URI de conflitos. |
| indexingPolicy | São as definições de política de indexação da coleção. |
| partitionKey | São as definições de configuração de criação de partições para a coleção. |
Propriedades em Caminhos Incluídos
| Propriedade | Descrição |
|---|---|
| caminho | Caminho ao qual o comportamento de indexação se aplica. Os caminhos de índice começam com a raiz (/) e normalmente terminam com o operador de caráter universal de ponto de interrogação (?), indicando que existem vários valores possíveis para o prefixo. Por exemplo, para servir SELECT * FROM Families F WHERE F.familyName = "Andersen", tem de incluir um caminho de índice para /familyName/? na política de índice da coleção. Os caminhos de índice também podem utilizar o operador de carateres universais * para especificar o comportamento dos caminhos de forma recursiva no prefixo. Por exemplo, /payload/* pode ser utilizado para excluir tudo na propriedade payload da indexação. |
| dataType | É o tipo de dados ao qual o comportamento de indexação é aplicado. Pode ser Cadeia, Número, Ponto, Polígono ou LineString. Os booleanos e os nulos são indexados automaticamente |
| tipo | O tipo de índice. Os índices de Hash são úteis para comparações de igualdade, enquanto os índices range são úteis para a igualdade, comparações de gama e triagem. Os índices espaciais são úteis para consultas espaciais. |
| precisão | A precisão do índice. Pode ser definido como -1 para precisão máxima ou entre 1-8 para Número e 1-100 para Cadeia. Não aplicável aos tipos de dados Point, Polygon e LineString . |
Propriedades em Caminhos Excluídos
| Propriedade | Descrição |
|---|---|
| caminho | Caminho excluído da indexação. Os caminhos de índice começam com a raiz (/) e normalmente terminam com o operador de carateres universais * . Por exemplo, /payload/* pode ser utilizado para excluir tudo na propriedade payload da indexação. |
Propriedades em Chave de Partição
| Propriedade | Descrição |
|---|---|
| caminhos | Uma matriz de caminhos com os quais os dados dentro da coleção podem ser particionados. Os caminhos não podem conter um caráter universal ou uma barra à direita. Por exemplo, a propriedade JSON "AccountNumber" é especificada como "/AccountNumber". A matriz tem de conter apenas um único valor. |
| tipo | O algoritmo utilizado para a criação de partições. Apenas o Hash é suportado. |
| versão | Um campo opcional, se não for especificado, o valor predefinido é 1. Para utilizar a chave de partição grande, defina a versão como 2. Para saber mais sobre chaves de partição grandes, veja como criar coleções com uma chave de partição grande . |
Corpo da resposta de exemplo
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Exemplo 1
O exemplo seguinte cria uma coleção com débito manual de 400 RU/s.
x-ms-offer-throughput o cabeçalho é utilizado para definir o valor de débito (RU/s). Aceita um número com um valor mínimo de 400 que incrementa por unidades de 100.
POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1
x-ms-offer-throughput: 400
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 235
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
HTTP/1.1 201 Created
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Mon, 28 Mar 2016 20:00:12.142 GMT
etag: "00005900-0000-0000-0000-56f9a2630000"
collection-partition-index: 0
collection-service-index: 24
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb
x-ms-quorum-acked-lsn: 9
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 4.95
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 05d0a3b5-4504-446a-96f4-bef3a3408595
x-ms-session-token: 0:10
Set-Cookie: x-ms-session-token#0=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=
Set-Cookie: x-ms-session-token=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Mon, 28 Mar 2016 21:30:12 GMT
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash"
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Exemplo 2
O exemplo seguinte cria uma coleção com um débito máximo de dimensionamento automático de 4000 RU/s (dimensiona entre 400 e 4000 RU/s).
x-ms-cosmos-offer-autopilot-settings o cabeçalho é utilizado para definir o maxThroughput valor, que é o valor máximo de RU/s de dimensionamento automático. Aceita um número com um mínimo de 4000 que incrementa por unidades de 1000. Quando o dimensionamento automático é utilizado, é necessária uma definição de chave de partição, conforme mostrado no exemplo seguinte:
Nota
Para ativar o dimensionamento automático numa base de dados ou coleção existente, ou mudar do dimensionamento automático para o débito manual, consulte o artigo Substituir uma Oferta.
POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1
x-ms-cosmos-offer-autopilot-settings: {"maxThroughput": 4000}
x-ms-date: Wed, 22 Jul 2020 22:17:39 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2018-12-31
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 235
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}