Koleksiyon Oluşturma

bu Create Collection işlem veritabanında yeni bir koleksiyon oluşturur.

Not

Bu API başvuru makalelerinde Azure Cosmos DB veri düzlemi API'sini kullanarak kaynak oluşturma adımları gösterilmektedir. Veri düzlemi API'siyle dizin oluşturma ilkesi, bölüm anahtarları gibi cosmos DB SDK'ları gibi temel seçenekleri yapılandırabilirsiniz. Tüm Azure Cosmos DB kaynakları için tam özellik desteğine ihtiyacınız varsa Cosmos DB Kaynak Sağlayıcısı'nı kullanmanızı öneririz.

İstek

Yöntem İstek URI'si Description
POST https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls {databaseaccount}, aboneliğiniz altında oluşturulan Azure Cosmos DB hesabının adıdır. {db-id}, veritabanının kimliği veya _rid değeri olabilir.

Üst Bilgiler

Tüm Azure Cosmos DB istekleri tarafından kullanılan üst bilgiler için bkz. Yaygın Azure Cosmos DB REST isteği üst bilgileri.

Ana anahtar belirteci için karma imza oluşturulurken ResourceType "colls" olmalıdır. ResourceId olmalıdır dbs/{db-id}; burada {db-id}, veritabanının kimliği veya _rid değeri olabilir.

Özellik Gerekli Tür Description
x-ms-offer-throughput İsteğe Bağlı Sayı Kullanıcı, koleksiyon için saniyede 100 istek birimi cinsinden ifade edilen el ile aktarım hızını (RU/sn) belirtti. En az 400 en fazla 1.000.000'dir (veya bir sınır artışı isteyerek daha yüksektir).

Veya'larından x-ms-offer-throughputx-ms-cosmos-offer-autopilot-settings yalnızca biri belirtilmelidir. Bu üst bilgiler birlikte belirtilemez.
x-ms-cosmos-offer-autopilot-settings İsteğe Bağlı JSON Kullanıcı otomatik ölçeklendirme maksimum RU/sn değerini belirtti. değeri özelliğine maxThroughputsahip bir JSON değeridir. Örneğin: {"maxThroughput": 4000}.

Veya'larından x-ms-offer-throughputx-ms-cosmos-offer-autopilot-settings yalnızca biri belirtilmelidir. Bu üst bilgiler birlikte belirtilemez.

Otomatik ölçeklendirme kullanıldığında partitionKey tanımı gerekir.
x-ms-offer-type İsteğe Bağlı Dize Bu, kullanımdan kaldırılmış S1, S2 ve S3 önceden tanımlanmış performans düzeyleri için eski bir üst bilgidir . Yukarıda açıklandığı gibi el ile veya otomatik ölçeklendirme aktarım hızı kullanmanız önerilir.

Gövde

Özellik Gerekli Tür Description
id Gerekli Dize Koleksiyon için kullanıcı tarafından oluşturulan benzersiz ad. Hiçbir iki koleksiyon aynı kimliklere sahip olamaz. 255 karakterden uzun olmaması gereken bir dizedir.
indexingPolicy İsteğe Bağlı Nesne Bu değer, dizin oluşturma ilkesini yapılandırmak için kullanılır. Varsayılan olarak dizin oluşturma, koleksiyondaki tüm belge yolları için otomatiktir.
partitionKey Gerekli Nesne Bu değer, verileri birden çok bölüme bölmek için kullanılacak bölüm anahtarını yapılandırmak için kullanılır.

Büyük bölüm anahtarı kullanmak için partitionKey özelliğinde sürümü 2 olarak belirtin.

REST API sürümü 2018-12-31 veya üzeriyse, koleksiyon bir partitionKey tanımı içermelidir. 2018-12-31'den eski sürümlerde partitionKey tanımı atlanarak ve aktarım hızının 400 ile 10.000 RU/sn arasında olduğundan emin olunarak el ile aktarım hızına sahip bölümlenmemiş eski bir koleksiyon oluşturulabilir. En iyi performans ve ölçeklenebilirlik için her zaman bir bölüm anahtarı ayarlamanız önerilir.

İyi bir bölüm anahtarı seçme hakkında bilgi edinin.

Örnek gövde yükü

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "automatic": true,  
    "indexingMode": "Consistent",  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "String",  
            "precision": -1,  
            "kind": "Range"  
          }  
        ]  
      }  
    ]  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash",
     "Version": 2

  }  
}

Yanıt

Create Collection, oluşturulan koleksiyonu yanıt gövdesi olarak döndürür.

Üst Bilgiler

Tüm Azure Cosmos DB yanıtları tarafından döndürülen üst bilgiler için bkz. Genel Azure Cosmos DB REST yanıt üst bilgileri.

Durum kodları

Aşağıdaki tabloda bu işlem tarafından döndürülen genel durum kodları listelenmektedir. Durum kodlarının tam listesi için bkz. HTTP Durum Kodları.

HTTP durum kodu Açıklama
201 Oluşturuldu İşlem başarılı oldu.
400 Hatalı İstek JSON gövdesi geçersiz. Eksik küme ayraçlarını veya tırnakları denetleyin.
409 Çakışma Yeni koleksiyon için sağlanan kimlik mevcut bir koleksiyon tarafından alınmıştır.
Alt durum kodu 1013 olan 404 Koleksiyon oluşturma işlemi hala devam ediyor.

Koleksiyon oluştururken zaman aşımı özel durumuyla karşılaşırsanız, koleksiyonun başarıyla oluşturulup oluşturulmadığını doğrulamak için bir okuma işlemi çalıştırın. Koleksiyon oluşturma işlemi başarılı olana kadar okuma işlemi bir özel durum oluşturur. Okuma işlemi durum kodu 404 ve alt durum kodu 1013 olan bir özel durum oluşturursa, koleksiyon oluşturma işleminin devam ediyor olduğu anlamına gelir. 200 veya 201 durum kodlarını alıncaya kadar okuma işlemini yeniden deneyin; bu kodlar koleksiyonun başarıyla oluşturulduğunu size bildirir.

Gövde

Özellik Açıklama
id Yeni koleksiyonu tanımlayan benzersiz addır.
_Kurtulmak Sistem tarafından oluşturulan bir özelliktir. Kaynak kimliği (_rid) benzersiz tanıtıcıdır ve aynı zamanda kaynak modelindeki kaynağı yığınında hiyerarşik bir düzen oluşturur. İzin kaynağının yerleşimi ve gezintisi için dahili olarak kullanılır.
_Ts Sistem tarafından oluşturulan bir özelliktir. Kaynağın son güncelleştirilmiş zaman damgasını belirtir. Değer bir zaman damgasıdır.
_Kendini Sistem tarafından oluşturulan bir özelliktir. Kaynak için benzersiz adreslenebilir URI'dir.
_Etag İyimser eşzamanlılık denetimi için gereken kaynak etag'ini temsil eden sistem tarafından oluşturulan bir özelliktir.
_Doktor Belge kaynağının adreslenebilir yolunu belirten sistem tarafından oluşturulan bir özelliktir.
_sprocs Saklı yordamlar (sprocs) kaynağının adreslenebilir yolunu belirten sistem tarafından oluşturulan bir özelliktir.
_Tetikleyiciler Tetikleyiciler kaynağının adreslenebilir yolunu belirten sistem tarafından oluşturulan bir özelliktir.
_udfs Kullanıcı tanımlı işlevler (udfs) kaynağının adreslenebilir yolunu belirten sistem tarafından oluşturulan bir özelliktir.
_Çakışma Çakışma kaynağının adreslenebilir yolunu belirten sistem tarafından oluşturulan bir özelliktir. Bir koleksiyondaki bir kaynak üzerinde yapılan işlem sırasında, çakışma oluşursa, kullanıcılar çakışmalar URI yolunda bir GET gerçekleştirerek çakışan kaynakları inceleyebilir.
indexingPolicy Koleksiyon için dizin oluşturma ilkesi ayarlarıdır.
partitionKey Koleksiyon için bölümleme yapılandırma ayarlarıdır.

Eklenen Yollar altındaki özellikler

Özellik Açıklama
Yolu Dizin oluşturma davranışının uygulandığı yol. Dizin yolları kök (/) ile başlar ve genellikle ön ek için birden çok olası değer olduğunu belirten soru işareti (?) joker işleciyle biter. Örneğin, SELECT * FROM Families F WHERE F.familyName = "Andersen" hizmeti vermek için /familyName/? için bir dizin yolu eklemeniz gerekir. öğesini seçin.

Dizin yolları, ön ek altında özyinelemeli olarak yolların davranışını belirtmek için * joker karakter işlecini de kullanabilir. Örneğin, /payload/* payload özelliğinin altındaki her şeyi dizin oluşturmanın dışında tutmak için kullanılabilir.
Datatype Dizin oluşturma davranışının uygulandığı veri türüdür. Dize, Sayı, Nokta, Çokgen veya LineString olabilir. Boole değerleri ve null değerleri otomatik olarak dizine eklenir
Tür Dizin türü. Karma dizinler eşitlik karşılaştırmaları için, Aralık dizinleri ise eşitlik, aralık karşılaştırmaları ve sıralama için yararlıdır. Uzamsal dizinler uzamsal sorgular için yararlıdır.
Hassas Dizinin duyarlığı. Maksimum duyarlık için -1 olarak veya Sayı için 1-8 arasında ve Dize için 1-100 olarak ayarlanabilir. Point, Polygon ve LineString veri türleri için geçerli değildir.

Dışlanan Yollar altındaki özellikler

Özellik Açıklama
Yolu Dizin oluşturmanın dışında tutulan yol. Dizin yolları kök (/) ile başlar ve genellikle * joker işleciyle biter. Örneğin, /payload/* payload özelliğinin altındaki her şeyi dizin oluşturmanın dışında tutmak için kullanılabilir.

Bölüm Anahtarı altındaki özellikler

Özellik Açıklama
Yol Koleksiyondaki hangi verilerin bölümlenebileceğini kullanan bir yol dizisi. Yollar joker karakter veya sondaki eğik çizgi içermemelidir. Örneğin, "AccountNumber" JSON özelliği "/AccountNumber" olarak belirtilir. Dizi yalnızca tek bir değer içermelidir.
Tür Bölümleme için kullanılan algoritma. Yalnızca Karma desteklenir.
Sürüm belirtilmezse, isteğe bağlı bir alan varsayılan değer 1'dir. Büyük bölüm anahtarını kullanmak için sürümü 2 olarak ayarlayın. Büyük bölüm anahtarları hakkında bilgi edinmek için büyük bölüm anahtarıyla koleksiyon oluşturma makalesine bakın.

Örnek yanıt gövdesi

{  
  "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/"  
}

Örnek 1

Aşağıdaki örnek, el ile 400 RU/sn aktarım hızına sahip bir koleksiyon oluşturur. x-ms-offer-throughput header, aktarım hızı (RU/sn) değerini ayarlamak için kullanılır. Minimum değeri 400 olan ve 100'lü birimlere göre artan bir sayı kabul eder.

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/"  
}

Örnek 2

Aşağıdaki örnek, 4000 RU/sn (400 - 4000 RU/sn arasında ölçeklendirilir) maksimum aktarım hızına sahip otomatik ölçeklendirmeye sahip bir koleksiyon oluşturur. x-ms-cosmos-offer-autopilot-settings üst bilgisi, maksimum RU/sn maxThroughput değerini otomatik ölçeklendirme olan değeri ayarlamak için kullanılır. En az 4000 olan ve 1000 birim artıran bir sayı kabul eder. Otomatik ölçeklendirme kullanıldığında, aşağıdaki örnekte gösterildiği gibi bir bölüm anahtarı tanımı gerekir:

Not

Mevcut bir veritabanı veya koleksiyonda otomatik ölçeklendirmeyi etkinleştirmek veya otomatik ölçeklendirmeden el ile aktarım hızına geçmek için Teklifi Değiştirme makalesine bakın.

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
  }  
}

Ayrıca Bkz.

  • Last updated on