Crear colección
La Create Collection operación crea una nueva colección en una base de datos.
Nota:
En estos artículos de referencia de API se muestra cómo crear recursos mediante la API del plano de datos de Azure Cosmos DB. Con la API del plano de datos, puede configurar opciones básicas, como la directiva de indexación, las claves de partición del mismo modo que puede usar los SDK de Cosmos DB. Si necesita compatibilidad completa con características para todos los recursos de Azure Cosmos DB, se recomienda usar el proveedor de recursos de Cosmos DB.
Solicitud
| Método | URI de solicitud | Descripción |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} es el nombre de la cuenta de Azure Cosmos DB creada en la suscripción. {db-id} puede ser el identificador o el valor _rid de la base de datos. |
encabezados
Consulte Encabezados de solicitud REST comunes de Azure Cosmos DB para ver los encabezados que usan todas las solicitudes de Azure Cosmos DB.
Al construir la firma con hash para el token de clave maestra, ResourceType debe ser "colls". ResourceId debe ser dbs/{db-id}, donde {db-id} puede ser el identificador o el valor _rid de la base de datos.
| Propiedad | Obligatorio | Tipo | Descripción |
|---|---|---|---|
| x-ms-offer-throughput | Opcionales | Number | El usuario especificó el rendimiento manual (RU/s) para la colección expresada en unidades de 100 unidades de solicitud por segundo. El mínimo es de 400 hasta 1000 000 (o superior solicitando un aumento del límite). Solo se debe especificar uno de x-ms-offer-throughput o x-ms-cosmos-offer-autopilot-settings . Estos encabezados no se pueden especificar juntos. |
| x-ms-cosmos-offer-autopilot-settings | Opcionales | JSON | El usuario especificó el escalado automático máximo de RU/s. El valor es un JSON con la propiedad maxThroughput. Por ejemplo: {"maxThroughput": 4000}.Solo se debe especificar uno de x-ms-offer-throughput o x-ms-cosmos-offer-autopilot-settings . Estos encabezados no se pueden especificar juntos. Cuando se usa el escalado automático, se requiere una definición partitionKey . |
| x-ms-offer-type | Opcionales | String | Se trata de un encabezado heredado para los niveles de rendimiento predefinidos S1, S2 y S3 que se han retirado. Se recomienda usar el rendimiento manual o de escalado automático, como se ha descrito anteriormente. |
Body
| Propiedad | Obligatorio | Tipo | Descripción |
|---|---|---|---|
| id | Obligatorio | String | Nombre único generado por el usuario para la colección. No puede haber dos colecciones con los mismos identificadores. Es una cadena que no debe tener más de 255 caracteres. |
| indexingPolicy | Opcionales | Object | Este valor se usa para configurar la directiva de indización. De forma predeterminada, la indización es automática para todas las rutas de acceso de documento dentro de la colección. |
| partitionKey | Obligatorio | Object | Este valor se usa para configurar la clave de partición que se usará para crear particiones de datos en varias particiones. Para usar la clave de partición grande, especifique la versión como 2 dentro de la propiedad partitionKey. Si la versión de la API REST es 2018-12-31 o posterior, la colección debe incluir una definición partitionKey . En versiones anteriores a 2018-12-31, se puede crear una colección heredada sin particiones con rendimiento manual omitiendo la definición partitionKey y asegurándose de que el rendimiento está entre 400 y 10 000 RU/s. Para obtener el mejor rendimiento y escalabilidad, se recomienda establecer siempre una clave de partición. Obtenga información sobre cómo elegir una buena clave de partición. |
Carga de cuerpo de ejemplo
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
Response
Create Collection devuelve la colección creada como un cuerpo de respuesta.
encabezados
Consulte Encabezados de respuesta REST comunes de Azure Cosmos DB para ver los encabezados devueltos por todas las respuestas de Azure Cosmos DB.
Códigos de estado
La tabla siguiente muestra los códigos de estado comunes que devuelve esta operación. Para obtener una lista completa de los códigos de estado, consulte Códigos de estado HTTP.
| Código de estado HTTP | Descripción |
|---|---|
| 201 Creado | La operación se realizó correctamente. |
| 400 - Solicitud incorrecta | El cuerpo JSON no es válido. Compruebe si faltan llaves o comillas. |
| 409 Conflicto | Una colección existente ha tomado el identificador proporcionado para la nueva colección. |
| 404 con un código de subestado de 1013 | La operación de creación de la colección todavía está en curso. |
Si encuentra una excepción de tiempo de espera al crear una colección, ejecute una operación de lectura para validar si la colección se creó correctamente. La operación de lectura emite una excepción hasta que la operación de creación de la colección se realiza correctamente. Si la operación de lectura produce una excepción con el código de estado 404 y el código de subestado de 1013, significa que la operación de creación de la colección sigue en curso. Vuelva a intentar la operación de lectura hasta que obtenga códigos de estado 200 o 201; estos códigos le permiten saber que la colección se ha creado correctamente.
Body
| Propiedad | Descripción |
|---|---|
| id | Es el nombre único que identifica la nueva colección. |
| _Librar | Es una propiedad generada por el sistema. El identificador de recurso (_rid) es un identificador único que también es jerárquico por la pila de recursos del modelo de recursos. Se usa internamente para la colocación y la navegación del recurso de permiso. |
| _Ts | Es una propiedad generada por el sistema. Especifica la última marca de tiempo actualizada del recurso. El valor es una marca de tiempo. |
| _propio | Es una propiedad generada por el sistema. Es el URI direccionable único para el recurso. |
| _Etag | Se trata de una propiedad generada por el sistema que representa la etag de recursos necesaria para el control de simultaneidad optimista. |
| _Doc | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de documentos. |
| _sprocs | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de procedimientos almacenados (sprocs). |
| _desencadenantes | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso desencadenador. |
| _Udfs | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de funciones definidas por el usuario (udfs). |
| _Conflictos | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de conflictos. Durante una operación en un recurso dentro de una colección, si se produce un conflicto, los usuarios pueden inspeccionar los recursos en conflicto realizando una operación GET en la ruta URI en conflicto. |
| indexingPolicy | Es la configuración de la directiva de indexación para la recopilación. |
| partitionKey | Es la configuración de creación de particiones para la recopilación. |
Propiedades en Rutas de acceso incluidas
| Propiedad | Descripción |
|---|---|
| path | Ruta de acceso a la que se aplica el comportamiento de indexación. Las rutas de acceso de índice comienzan con la raíz (/) y suelen terminar con el operador comodín de signo de interrogación (?), lo que indica que hay varios valores posibles para el prefijo. Por ejemplo, para atender la consulta SELECT * FROM Families F WHERE F.familyName = "Andersen", debe incluir una ruta de acceso de índice para /familyName/? en la directiva de índice de la colección. Las rutas de acceso del índice también pueden usar el operador comodín * para especificar el comportamiento de las rutas de acceso de forma recursiva en el prefijo. Por ejemplo, /payload/* puede usarse para excluir de la indexación a todo el contenido de la propiedad payload. |
| dataType | Es el tipo de datos al que se aplica el comportamiento de indexación. Puede ser String, Number, Point, Polygon o LineString. Los valores booleanos y los valores NULL se indexan automáticamente |
| kind | Tipo de índice. Los índices hash son útiles para las comparaciones de igualdad, mientras que los índices range son útiles para la igualdad, las comparaciones de intervalos y la ordenación. Los índices espaciales son útiles para las consultas espaciales. |
| precisión | Precisión del índice. Puede establecerse en -1 para la precisión máxima o entre 1 y 8 para Number y 1-100 para String. No es aplicable a los tipos de datos Point, Polygon y LineString . |
Propiedades en Rutas de acceso excluidas
| Propiedad | Descripción |
|---|---|
| path | Ruta de acceso que se excluye de la indexación. Las rutas de acceso de índice comienzan con la raíz (/) y suelen terminar con el operador comodín * . Por ejemplo, /payload/* puede usarse para excluir de la indexación a todo el contenido de la propiedad payload. |
Propiedades en Clave de partición
| Propiedad | Descripción |
|---|---|
| Rutas de acceso | Matriz de rutas de acceso mediante las que se pueden particionar los datos de la colección. Las rutas de acceso no deben contener un carácter comodín ni una barra diagonal final. Por ejemplo, la propiedad JSON "AccountNumber" se especifica como "/AccountNumber". La matriz solo debe contener un único valor. |
| kind | Algoritmo utilizado para la creación de particiones. Solo se admite hash. |
| version | Un campo opcional, si no se especifica, el valor predeterminado es 1. Para usar la clave de partición grande, establezca la versión en 2. Para obtener información sobre las claves de partición grandes, consulte el artículo Creación de colecciones con clave de partición grande . |
Cuerpo de respuesta de ejemplo
{
"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/"
}
Ejemplo 1
En el ejemplo siguiente se crea una colección con un rendimiento manual de 400 RU/s.
x-ms-offer-throughput el encabezado se usa para establecer el valor de rendimiento (RU/s). Acepta un número con un valor mínimo de 400 que aumenta en 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/"
}
Ejemplo 2
En el ejemplo siguiente se crea una colección con un rendimiento máximo de escalabilidad automática de 4000 RU/s (se escala entre 400 y 4000 RU/s).
x-ms-cosmos-offer-autopilot-settings el encabezado se usa para establecer el maxThroughput valor , que es el valor máximo de RU/s de escalabilidad automática. Acepta un número con un mínimo de 4000 que aumenta en unidades de 1000. Cuando se usa la escalabilidad automática, se requiere una definición de clave de partición, como se muestra en el ejemplo siguiente:
Nota:
Para habilitar el escalado automático en una base de datos o colección existente, o cambiar de escalabilidad automática a rendimiento manual, consulte el artículo Reemplazar una 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
}
}