Criar Coleção
A Create Collection operação cria uma nova coleção em um banco de dados.
Observação
Esses artigos de referência de API mostram como criar recursos usando a API do plano de dados do Azure Cosmos DB. Com a API do plano de dados, você pode configurar opções básicas, como a política de indexação, chaves de partição como você pode com SDKs do Cosmos DB. Se você precisar de suporte completo para todos os recursos do Azure Cosmos DB, recomendamos usar o Provedor de Recursos do Cosmos DB.
Solicitação
| Método | URI da solicitação | Descrição |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} é o nome da conta do Azure Cosmos DB criada em sua assinatura. {db-id} pode ser a ID ou o valor _rid para o banco de dados. |
Cabeçalhos
Confira Cabeçalhos comuns de solicitação REST do Azure Cosmos DB para obter cabeçalhos usados por todas as solicitações do Azure Cosmos DB.
Ao construir a assinatura hash para o token de chave master, o ResourceType deve ser "colls". O ResourceId deve ser dbs/{db-id}, em que {db-id} pode ser a ID ou o valor _rid do banco de dados.
| Propriedade | Obrigatório | Type | Descrição |
|---|---|---|---|
| x-ms-offer-throughput | Opcional | Número | O usuário especificou a taxa de transferência manual (RU/s) para a coleção expressa em unidades de 100 unidades de solicitação por segundo. O mínimo é de 400 até 1.000.000 (ou superior, solicitando um aumento de limite). Apenas um de x-ms-offer-throughput ou x-ms-cosmos-offer-autopilot-settings deve ser especificado. Esses cabeçalhos não podem ser especificados juntos. |
| x-ms-cosmos-offer-autopilot-settings | Opcional | JSON | O usuário especificou o máximo de RU/s de dimensionamento automático. O valor é um JSON com a propriedade maxThroughput. Por exemplo: {"maxThroughput": 4000}.Apenas um de x-ms-offer-throughput ou x-ms-cosmos-offer-autopilot-settings deve ser especificado. Esses cabeçalhos não podem ser especificados juntos. Quando o dimensionamento automático é usado, uma definição partitionKey é necessária. |
| x-ms-offer-type | Opcional | String | Esse é um cabeçalho herdado para os níveis de desempenho predefinidos S1, S2 e S3 que foram desativados. É recomendável que você use a taxa de transferência manual ou de dimensionamento automático, conforme descrito acima. |
Corpo
| Propriedade | Obrigatório | Type | Descrição |
|---|---|---|---|
| id | Obrigatório | String | O nome exclusivo gerado pelo usuário para a coleção. Nenhuma coleção pode ter as mesmas IDs. É uma cadeia de caracteres que não deve ter mais de 255 caracteres. |
| indexingPolicy | Opcional | Objeto | Esse valor é usado para configurar a política de indexação. Por padrão, a indexação é automática para todos os caminhos de documento dentro da coleção. |
| partitionKey | Obrigatório | Objeto | Esse valor é usado para configurar a chave de partição a ser usada para particionar dados em várias partições. Para usar uma chave de partição grande, especifique a versão como 2 dentro da propriedade partitionKey. Se a versão da API REST for 2018-12-31 ou superior, a coleção deverá incluir uma definição partitionKey . Em versões anteriores a 2018-12-31, uma coleção não particionada herdada com taxa de transferência manual pode ser criada omitindo a definição partitionKey e garantindo que a taxa de transferência esteja entre 400 a 10.000 RU/s. Para obter o melhor desempenho e escalabilidade, é recomendável sempre definir uma chave de partição. Saiba mais sobre como escolher uma boa chave de partição. |
Conteúdo do corpo do 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
Create Collection retorna a coleção criada como um corpo de resposta.
Cabeçalhos
Consulte Cabeçalhos comuns de resposta REST do Azure Cosmos DB para obter cabeçalhos retornados por todas as respostas do Azure Cosmos DB.
Códigos de status
A tabela a seguir lista os códigos de status comuns retornados por esta operação. Para obter uma lista completa de códigos de status, consulte Códigos de status HTTP.
| Código de status HTTP | Descrição |
|---|---|
| 201 Criado | A operação foi bem-sucedida. |
| 400 Solicitação Inválida | O corpo JSON é inválido. Verifique por colchetes ou aspas ausentes. |
| 409 Conflito | A ID fornecida para a nova coleção foi obtida por uma coleção existente. |
| 404 com um código de sub-status de 1013 | A operação de criação da coleção ainda está em andamento. |
Se você 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 gerar uma exceção com status código de 404 e sub-status código de 1013, isso significa que a operação de criação da coleção ainda está em andamento. Repita a operação de leitura até obter 200 ou 201 códigos de status, esses códigos informam que a coleção foi criada com êxito.
Corpo
| Propriedade | Descrição |
|---|---|
| id | É o nome exclusivo que identifica a nova coleção. |
| _Livrar | É uma propriedade gerada pelo sistema. A ID de recurso (_rid) é um identificador exclusivo que também é hierárquico pela pilha de recurso no modelo de recurso. É usada internamente para posicionamento 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. |
| _Auto | É uma propriedade gerada pelo sistema. É o URI endereçável exclusivo do recurso. |
| _Etag | É uma propriedade gerada pelo sistema que representa a etag de recurso necessária para o controle 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). |
| _Gatilhos | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de gatilhos. |
| _Udfs | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso udfs (funções definidas pelo usuário). |
| _Conflitos | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de conflitos. Durante uma operação em um recurso dentro de uma coleção, se ocorrer um conflito, os usuários podem inspecionar os recursos conflitantes executando um GET no caminho do URI de conflitos. |
| indexingPolicy | São as configurações de política de indexação para coleção. |
| partitionKey | São as configurações de particionamento da coleção. |
Propriedades em Caminhos Incluídos
| Propriedade | Descrição |
|---|---|
| path | 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 curinga de ponto de interrogação (?), indicando que há vários valores possíveis para o prefixo. Por exemplo, para servir SELECT * FROM Families F WHERE F.familyName = "Andersen", você deve incluir um caminho de índice para /familyName/? na política de índice da coleção. Os caminhos de índice também podem usar o operador curinga * para especificar o comportamento de caminhos recursivamente no prefixo. Por exemplo, /payload/* pode ser usado para excluir tudo na propriedade de conteúdo da indexação. |
| dataType | É o tipo de dados ao qual o comportamento de indexação é aplicado. Pode ser String, Number, Point, Polygon ou LineString. Boolianos e nulos são indexados automaticamente |
| kind | O tipo do índice. Índices de hash são úteis para comparações de igualdade, enquanto índices range são úteis para igualdade, comparações de intervalo e classificação. Í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 de Caracteres. Não aplicável aos tipos de dados Point, Polygon e LineString . |
Propriedades em Caminhos Excluídos
| Propriedade | Descrição |
|---|---|
| path | Caminho excluído da indexação. Os caminhos de índice começam com a raiz (/) e normalmente terminam com o operador curinga * . Por exemplo, /payload/* pode ser usado para excluir tudo na propriedade de conteúdo da indexação. |
Propriedades em Chave de Partição
| Propriedade | Descrição |
|---|---|
| caminhos | Uma matriz de caminhos usando quais dados dentro da coleção podem ser particionados. Os caminhos não devem conter um curinga ou uma barra à direita. Por exemplo, a propriedade JSON "AccountNumber" é especificada como "/AccountNumber". A matriz deve conter apenas um único valor. |
| kind | O algoritmo usado para particionamento. Há suporte apenas para Hash. |
| version | Um campo opcional, se não for especificado, o valor padrão será 1. Para usar a chave de partição grande, defina a versão como 2. Para saber mais sobre chaves de partição grandes, confira o artigo Como criar coleções com 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 a seguir cria uma coleção com taxa de transferência manual de 400 RU/s. x-ms-offer-throughput o cabeçalho é usado para definir o valor de taxa de transferência (RU/s). Ele aceita um número com 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 a seguir cria uma coleção com uma taxa de transferência máxima de dimensionamento automático de 4000 RU/s (ela é dimensionada entre 400 e 4000 RU/s). x-ms-cosmos-offer-autopilot-settings o cabeçalho é usado para definir o maxThroughput valor , que é o valor máximo de RU/s de dimensionamento automático. Ele aceita um número com um mínimo de 4.000 incrementos por unidades de 1000. Quando o dimensionamento automático é usado, uma definição de chave de partição é necessária, conforme mostrado no exemplo a seguir:
Observação
Para habilitar o dimensionamento automático em um banco de dados ou coleção existente ou alternar do dimensionamento automático para a taxa de transferência 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
}
}