Ersetzen einer Sammlung
Replace Collection unterstützt das Ändern der Indizierungsrichtlinie einer Sammlung nach der Erstellung. Das Ändern anderer Eigenschaften einer Sammlung wie die ID oder den Partitionsschlüssel wird nicht unterstützt.
Hinweis
In diesen API-Referenzartikeln wird gezeigt, wie Ressourcen mithilfe der Azure Cosmos DB-Datenebenen-API erstellt werden. Mit der Datenebenen-API können Sie grundlegende Optionen wie Indizierungsrichtlinie und Partitionsschlüssel wie bei Cosmos DB SDKs konfigurieren. Wenn Sie vollständige Featureunterstützung für alle Azure Cosmos DB-Ressourcen benötigen, empfiehlt es sich, den Cosmos DB-Ressourcenanbieter zu verwenden.
Anforderung
| Methode | Anforderungs-URI | BESCHREIBUNG |
|---|---|---|
| PUT | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id} | {databaseaccount} ist der Name des Azure Cosmos DB-Kontos, das unter Ihrem Abonnement erstellt wurde. Der Wert {db-id} ist der vom Benutzer generierte Name/id der Datenbank, nicht die vom System generierte ID (rid). Der Wert {coll-id} ist der Name der zu ersetzenden Auflistung. |
Header
Informationen zu Headern, die von allen Cosmos DB-Anforderungen verwendet werden, finden Sie unter Allgemeine Azure Cosmos DB-REST-Anforderungsheader .
Body
| Eigenschaft | Erforderlich | type | BESCHREIBUNG |
|---|---|---|---|
| id | Erforderlich | String | Der vom Benutzer generierte eindeutige Name für die Auflistung. Zwei Auflistungen können nicht die gleichen IDs aufweisen. Es ist eine Zeichenfolge, die nicht mehr als 255 Zeichen sein darf. |
| indexingPolicy | Optional | Object | Dieser Wert wird verwendet, um die Indizes für die Elemente der Auflistung zu konfigurieren. Standardmäßig ist die Indizierungsrichtlinie für alle Dokumentpfade innerhalb der Sammlung auf automatisch festgelegt. |
| partitionKey | Erforderlich | Object | Dieser Wert legt den Partitionsschlüssel fest, der für die Datenpartitionierung verwendet wird. Um einen großen Partitionsschlüssel zu verwenden, geben Sie die Version 2 in der partitionKey-Eigenschaft an. Wenn die REST-API-Version 2018-12-31 oder höher ist, muss die Auflistung eine partitionKey-Definition enthalten. In Versionen, die älter als 2018-12-31 sind, kann eine nicht partitionierte Legacysammlung mit manuellem Durchsatz erstellt werden, indem die partitionKey-Definition weggelassen und sichergestellt wird, dass der Durchsatz zwischen 400 und 10.000 RU/s liegt. Um eine optimale Leistung und Skalierbarkeit zu erzielen, wird empfohlen, immer einen Partitionsschlüssel festzulegen. Erfahren Sie, wie Sie einen guten Partitionsschlüssel auswählen. |
Hinweis
Beim Festlegen von benutzerdefinierten Indexpfaden müssen Sie die Standardindizierungsregel für die gesamte Dokumentstruktur angeben, die durch den speziellen Pfad „/*“ gekennzeichnet ist.
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "Number",
"precision": -1,
"kind": "Range"
},
{
"dataType": "String",
"precision": 3,
"kind": "Hash"
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203135,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Antwort
Replace Collection gibt die aktualisierte Auflistung als Antworttext zurück.
Header
Informationen zu Headern, die von allen Cosmos DB-Antworten zurückgegeben werden, finden Sie unter Allgemeine Azure Cosmos DB-REST-Antwortheader .
Statuscodes
In der folgenden Tabelle sind die allgemeinen Statuscodes aufgeführt, die von diesem Vorgang zurückgegeben werden. Eine vollständige Liste der status Codes finden Sie unter HTTP-Statuscodes.
| Code | BESCHREIBUNG |
|---|---|
| 201 OK | Der PUT-Vorgang war erfolgreich. |
| 400 – Ungültige Anforderung | Der JSON-Text ist ungültig. Überprüfen Sie, ob geschweifte Klammern oder Anführungszeichen fehlen. |
Body
| Eigenschaft | BESCHREIBUNG |
|---|---|
| id | Es ist der eindeutige Name, der die neue Sammlung identifiziert. |
| _rid | Es handelt sich um eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch gemäß dem Ressourcenstapel für das Ressourcenmodell hierarchisch ist. Sie wird intern für die Platzierung und Navigation der Berechtigungsressource verwendet. |
| _ts | Es handelt sich um eine vom System generierte Eigenschaft. Sie gibt den zuletzt aktualisierten Zeitstempel der Ressource an. Der Wert ist ein Zeitstempel. |
| _self | Es handelt sich um eine vom System generierte Eigenschaft. Es handelt sich um den eindeutigen, adressierbaren URI für die Ressource. |
| _etag | Es handelt sich um eine vom System generierte Eigenschaft, die das Ressourcen-Etag darstellt, das für die Steuerung der optimistischen Parallelität erforderlich ist. |
| _doc | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Dokumentressource angibt. |
| _sprocs | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Ressource gespeicherte Prozeduren (Sprocs) angibt. |
| _triggers | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Triggerressource angibt. |
| _udfs | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der ressource benutzerdefinierte Funktionen (udfs) angibt. |
| _conflicts | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Konfliktressource angibt. Wenn während eines Vorgangs für eine Ressource in einer Auflistung ein Konflikt auftritt, können Benutzer Ressourcen überprüfen, die einen Konflikt verursachen, indem sie einen GET-Aufruf für den URI-Pfad des Konflikts ausführen. |
| indexingPolicy | Dies sind die Indizierungsrichtlinieneinstellungen für die Sammlung. |
| partitionKey | Dies sind die Partitionierungskonfigurationseinstellungen für die Sammlung. |
Eigenschaften unter Eingeschlossene Pfade
| Eigenschaft | Beschreibung |
|---|---|
| path | Pfad, für den das Indizierungsverhalten gilt. Indexpfade beginnen mit dem Stamm (/) und enden in der Regel mit dem Platzhalterzeichen "?", das angibt, dass mehrere mögliche Werte für das Präfix verfügbar sind. Für SELECT * FROM Families F WHERE F.familyName = "Andersen" müssen Sie z. B. einen Indexpfad für /familyName/? in die Indexrichtlinie der Sammlung einbinden. Indexpfade können auch das Platzhalterzeichen * verwenden, um das Verhalten für Pfade rekursiv unter dem Präfix anzugeben. Beispielsweise kann „/payload/*“ dazu verwendet werden, um sämtliche Elemente unter der payload-Eigenschaft von der Indizierung auszuschließen. |
| dataType | Dies ist der Datentyp, auf den das Indizierungsverhalten angewendet wird. Dies kann String, Number, Point*, Polygon oder LineString sein. Boolesche Werte und NULL-Werte werden automatisch indiziert. |
| kind | Der Indextyp. Hashindizes sind für Gleichheitsvergleiche nützlich, während Bereichsindizes für Gleichheit, Bereichsvergleiche und Sortierung nützlich sind. Räumliche Indizes sind für räumliche Abfragen nützlich. |
| precision (Genauigkeit) | Die Genauigkeit des Indexes. Kann entweder auf -1 für maximale Genauigkeit oder zwischen 1 und 8 für Zahl und 1 bis 100 für String festgelegt werden. Gilt nicht für dieDatentypen Point, Polygon und LineString . |
Eigenschaften unter Ausgeschlossene Pfade
| Eigenschaft | Beschreibung |
|---|---|
| path | Pfad, der von der Indizierung ausgeschlossen ist. Indexpfade beginnen mit dem Stamm (/) und enden in der Regel mit dem * -Wildcard-Operator. Beispielsweise kann „/payload/*“ dazu verwendet werden, um sämtliche Elemente unter der payload-Eigenschaft von der Indizierung auszuschließen. |
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "Number",
"precision": -1
},
{
"kind": "Hash",
"dataType": "String",
"precision": 3
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203136,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Beispiel
PUT https://querydemo.documents.azure.com/dbs/XrdaAA==/colls/XrdaAKx3Hgw= HTTP/1.1
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dZY2s2H1TuPFKk1H2od5qVLbn57vjI9rKz0CMXKOk3GA%3d
Cache-Control: no-cache
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 475
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "Number",
"precision": -1,
"kind": "Range"
},
{
"dataType": "String",
"precision": 3,
"kind": "Hash"
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203135,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
HTTP/1.1 200 Ok
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Location: https://querydemo.documents.azure.com/dbs/XrdaAA==/colls/XrdaAKx3Hgw=
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:54:09.213 GMT
etag: "00006e00-0000-0000-0000-56f9ac400000"
x-ms-resource-quota: collections=5000;
x-ms-resource-usage: collections=28;
collection-partition-index: 0
collection-service-index: 0
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb
x-ms-quorum-acked-lsn: 7902
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 9.9
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 6050a48c-828d-4016-b73b-5e0ce2ad6271
x-ms-session-token: M:7903
Set-Cookie: x-ms-session-token#M=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=
Set-Cookie: x-ms-session-token=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Mon, 28 Mar 2016 22:12:15 GMT
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "Number",
"precision": -1
},
{
"kind": "Hash",
"dataType": "String",
"precision": 3
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203136,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}