REST API kullanarak Azure Cosmos DB kaynaklarını sorgulama

Makale
07/19/2023

Azure Cosmos DB birden çok API desteği olan global olarak dağıtılmış, çok modelli bir veritabanıdır. Bu makalede, SQL API'sini kullanarak kaynakları sorgulamak için REST'in nasıl kullanılacağı açıklanmaktadır.

REST kullanarak bir kaynağı sorgulamak Nasıl yaparım??

Bir kaynakta SQL sorgusu gerçekleştirmek için aşağıdakileri yapın:

POST JSON query kullanarak bir kaynak yoluna karşı bir yöntem yürütürken özelliği SQL sorgu dizesine, "parameters" özelliği de isteğe bağlı parametre değerleri dizisine ayarlanmıştır.
Üst bilgiyi x-ms-documentdb-isquery olarak Trueayarlayın.
Üst bilgiyi Content-Type olarak application/query+jsonayarlayın.

.NET kullanarak bir kaynakta SQL sorgusu gerçekleştirmeyi gösteren bir örnek için bkz. .NET Örneğinden REST.

Örnek

Aşağıda belge kaynakları üzerinde örnek bir REST sorgu işlemi verilmiştir. Bu örnekte, yazar olarak "Don" içeren tüm belgeleri bulmak istiyoruz.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-12-16  
x-ms-query-enable-crosspartition: True  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  

{  
    "query": "SELECT * FROM root WHERE (root.Author.id = 'Don')",  
    "parameters": []  
}

İstek Ayrıntıları

Yöntem	İstek URI'si
POST	Gerekli. Kimlik doğrulama türü ve imza belirteci. Bu işlem için yalnızca ana anahtar belirtecinin kullanılmasına izin verilir. Daha fazla bilgi için bkz. Cosmos DB Kaynakları hakkında Access Control.

İstek Üst Bilgileri

Aşağıdaki tabloda sorgu işlemlerini gerçekleştirmek için kullanılan ortak üst bilgiler yer alır.

Standart Üst Bilgi	Açıklama
Yetkilendirme	Gerekli. Kimlik doğrulama türü ve imza belirteci. Bu işlem için yalnızca ana anahtar belirtecinin kullanılmasına izin verilir. Daha fazla bilgi için bkz. Cosmos DB Kaynakları hakkında Access Control.
İçerik Türü	Gerekli. application/query+json olarak ayarlanmalıdır.
Kabul Etme	İsteğe bağlı. Şu anda Cosmos DB her zaman yanıt yükünü standart JSON biçiminde döndürür. İstemcinin yanıt gövdesini standart JSON biçiminde kabul edebilmesi gerekir.
Kullanıcı Aracısı	İsteğe bağlı. İsteği gerçekleştiren kullanıcı aracısı. Önerilen biçim :{kullanıcı aracısı adı}/{version}. Örneğin, SQL API .NET SDK'sı User-Agent dizesini Microsoft.Document.Client/1.0.0.0 olarak ayarlar.

Özel Üst Bilgi	Açıklama
x-ms-date	Gerekli. RFC 1123'te belirtildiği gibi isteğin tarihi. Tarih biçimi, örneğin Eşgüdümlü Evrensel Saat (UTC) olarak ifade edilir. Cum, 08 Nis 2015 03:52:31 GMT.
x-ms-documentdb-isquery	Gerekli. Bu özellik true olarak ayarlanmalıdır.
x-ms-max-item-count	İsteğe bağlı. Bir sonuç kümesinde sayfalandırmak için, bu üst bilgiyi tek bir sayfada döndürülecek öğe sayısı üst sınırına ayarlayın.
x-ms-continuation	İsteğe bağlı. Sonraki öğe sayfasına gitmek için bu üst bilgiyi sonraki sayfanın devamlılık belirtecine ayarlayın.
x-ms-version	İsteğe bağlı. Cosmos DB REST hizmetinin sürümü. Üst bilgi sağlanmadığında en son sürüm kullanılır. Daha fazla bilgi için bkz. Azure Cosmos DB REST API Başvurusu.
x-ms-documentdb-query-enable-scan	İsteğe bağlı. Doğru türdeki dizin yolu kullanılamıyorsa sorguyu işlemek için dizin taraması kullanın.
x-ms-session-token	İsteğe bağlı. İsteğin oturum belirteci. Oturum tutarlılığı için kullanılır.
x-ms-partition-key	İsteğe bağlı. Belirtilirse, sorgu yalnızca üst bilgideki bölüm anahtarı değeriyle eşleşen belgelerde yürütülür.
x-ms-documentdb-query-enablecrosspartition	İsteğe bağlı. Tek bir bölüm anahtarına göre filtreleme yapmayan sorgular için true olarak ayarlanmalıdır. Tek bir bölüm anahtarı değerine göre filtreleyen sorgular, true olarak ayarlansa bile yalnızca tek bir bölüme karşı yürütülür.
x-ms-documentdb-populatequerymetrics	İsteğe bağlı. Sorgu ölçümlerini döndürmek `True` için olarak ayarlanmalıdır

İstek Gövdesi

İstek gövdesi, SQL sorgusunu ve parametrelerini içeren geçerli bir JSON belgesi olmalıdır. Giriş yanlış biçimlendirilmişse veya geçersiz SQL söz dizimiyse, ile işlem 400 Hatalı İstek hatasıyla başarısız olur.

Ayrıca ağ geçidi tarafından bir sorgu sunulamazsa 400 hatalı istek alırsınız.

Özellik	Açıklama
query	Gerekli. Sorgunun SQL sorgu dizesi. Daha fazla bilgi için bkz. Azure Cosmos DB SQL söz dizimi başvurusu.
parameters	Gerekli. Ad değer çiftleri olarak belirtilen parametrelerin JSON dizisi. parametre dizisi sıfırdan birçok parametreye kadar olabilir. Her parametrenin şu değerlere sahip olması gerekir: name: parametrenin adı. Parametre adları geçerli dize değişmez değerleri olmalı ve '@' ile başlamalıdır. value: parametresinin değeri. Herhangi bir geçerli JSON değeri (dize, sayı, nesne, dizi, Boole veya null) olabilir.

Özellik

Açıklama

query

Gerekli. Sorgunun SQL sorgu dizesi. Daha fazla bilgi için bkz. Azure Cosmos DB SQL söz dizimi başvurusu.

parameters

Gerekli. Ad değer çiftleri olarak belirtilen parametrelerin JSON dizisi. parametre dizisi sıfırdan birçok parametreye kadar olabilir. Her parametrenin şu değerlere sahip olması gerekir: name: parametrenin adı. Parametre adları geçerli dize değişmez değerleri olmalı ve '@' ile başlamalıdır. value: parametresinin değeri. Herhangi bir geçerli JSON değeri (dize, sayı, nesne, dizi, Boole veya null) olabilir.

İstek Örneği

Aşağıdaki örnek, için @authorbir dize parametresiyle parametreli bir SQL isteği yapar.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-04-08  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  
  
{  
    "query": "SELECT * FROM root WHERE (root.Author.id = @author)",  
    "parameters":   
    [  
        { "name": "@author", "value": "Leo Tolstoy"}  
    ]  
}

SQL sorguları hakkında daha fazla bilgi için bkz. Azure Cosmos DB için SQL sorguları.

Yanıt Ayrıntıları

Bu işlem tarafından döndürülen yaygın durum kodları aşağıdadır. Hata durum kodları hakkında bilgi için bkz. Azure Cosmos DB için HTTP Durum Kodları.

Kod	Açıklama
200 Tamam	İşlem başarılı oldu.
400 Hatalı İstek	SQL deyiminin söz dizimi yanlış.
401 Yetkisiz	Yetkilendirme veya x-ms-date üst bilgisi ayarlanmadı. Yetkilendirme üst bilgisi geçersiz yetkilendirme belirtecine ayarlandığında da 401 döndürülür.
403 Yasak	Yetkilendirme belirtecinin süresi doldu.
404 Bulunamadı	Koleksiyon artık bir kaynak değil. Örneğin, kaynak silinmiş olabilir.

Yanıt Üst Bilgileri

Bu işlem aşağıdaki ortak üst bilgileri döndürür. Başka standart ve ortak üst bilgiler döndürülebilir.

Standart Üst Bilgi	Açıklama
İçerik Türü	content-type, application/json şeklindedir. Cosmos DB her zaman yanıt gövdesini standart JSON biçiminde döndürür.
Date	Yanıt işleminin tarih-saati. Bu tarih saat biçimi UTC ile ifade edilen [RFC1123] tarih saat biçimine uygundur.

Özel Üst Bilgi	Açıklama
x-ms-item-count	İşlem tarafından döndürülen öğe sayısı.
x-ms-continuation	Sorgunun alınması gereken daha fazla öğe olduğunda döndürülen opak bir dizedir. x-ms-continuation, sorgunun yürütülmesini sürdürmek için sonraki isteklere istek üst bilgisi olarak eklenebilir.
x-ms-request-charge	İşlem tarafından kullanılan istek birimi (RU) sayısıdır. İstek birimleri hakkında daha fazla bilgi için bkz. Azure Cosmos DB'de İstek Birimleri.
x-ms-activity-id	İşlem için benzersiz bir tanımlayıcıdır. Cosmos DB isteklerinin yürütülmesini izleme amacıyla kullanılabilir.
x-ms-session-token	Sonraki istekler için kullanılacak oturum belirteci. Oturum tutarlılığı için kullanılır.

Yanıt Gövdesi

Sorgu işleminin yanıt gövdesi sorgulanan kaynağın üst kaynağının _rid ve projeksiyon ve seçim için kaynak özelliklerini içeren kaynak dizisini içerir. Örnekte olduğu gibi, koleksiyonun docs yolunda XP0mAJ3H-AA= _rid bir sorgu gerçekleştirildiyse, yanıt şu şekilde olacaktır:

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}

Özellik	Açıklama
_Kurtulmak	Sorguda kullanılan koleksiyonun kaynak kimliği.
_Sayısı	Döndürülen öğe sayısı.
Kaynak dizisi	Sorgu sonuçlarını içeren dizi.

Sorgu isteği gövdesini oluşturma

Sorgu isteği, geçerli bir SQL sorgu dizesi ve isteğe bağlı parametreler dizisi içeren bir parametre özelliği içeren sorgu özelliğini içeren geçerli bir JSON belgesi olmalıdır. Her parametre, sorguda belirtilen parametrelerin bir ad ve değer özelliğine sahip olmalıdır. Parametre adları "@" karakteriyle başlamalıdır. Değerler herhangi bir geçerli JSON değeri olabilir: dizeler, tamsayılar, Boole değerleri ve null değerler.

Sorgu metninde belirtilen parametrelerin yalnızca bir alt kümesini belirtmek geçerlidir. Bu belirtilmemiş parametrelere başvuran ifadeler tanımsız olarak değerlendirilir. Sorgu metninde kullanılmayan ek parametreleri belirtmek de geçerlidir.

Geçerli sorgu isteklerinin bazı örnekleri aşağıda gösterilmiştir. Örneğin, aşağıdaki sorgunun tek bir parametresi @idvardır.

{  
    "query": "select * from docs d where d.id = @id",   
    "parameters": [   
        {"@id": "newdoc"}   
     ]  
}

Aşağıdaki örnekte biri dize değerine, diğeri tamsayı değerine sahip olmak üzere iki parametre vardır.

{  
    "query": "select * from docs d where d.id = @id and d.prop = @prop",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@prop": 5}   
     ]  
}

Aşağıdaki örnek, SELECT yan tümcesi içindeki parametrelerin yanı sıra parametre adı üzerinden parametre olarak erişilen bir özelliği kullanır.

{  
    "query": "select @id, d[@propName] from docs d",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@propName": "prop"}  
     ]  
}

Ağ geçidi tarafından hizmet veremeyen sorgular

Devamlılıklar arasında durum gerektiren herhangi bir sorgu ağ geçidi tarafından sunulmaz. Şunları içerir:

TOP
SİPARİŞ VEREN
KAYDIRMA SINIRI
Toplamalar
DISTINCT
GROUP BY

Ağ geçidi tarafından sunulan sorgular şunlardır:

Basit projeksiyonlar
Filtreler

Ağ geçidi tarafından sunulmayacak bir sorgu için yanıt döndürülürse, 400 (BadRequest) durum kodunu ve aşağıdaki iletiyi içerir:

{"code":"BadRequest","message":"The provided cross partition query can not be directly served by the gateway. 
This is a first chance (internal) exception that all newer clients will know how to handle gracefully. 
This exception is traced, but unless you see it bubble up as an exception (which only happens on older SDK clients), 
then you can safely ignore this message.\r\nActivityId: db660ee4-350a-40e9-bc2c-99f92f2b445d, Microsoft.Azure.Documents.Common/2.2.0.0",
"additionalErrorInfo":"{\"partitionedQueryExecutionInfoVersion\":2,\"queryInfo\":{\"distinctType\":\"None\",\"top\":null,\"offset\":null,\"limit\":null,
\"orderBy\":[\"Ascending\"],\"orderByExpressions\":[\"c._ts\"],\"aggregates\":[],
\"rewrittenQuery\":\"SELECT c._rid, [{\\\"item\\\": c._ts}] AS orderByItems, 
c AS payload\\nFROM c\\nWHERE ({documentdb-formattableorderbyquery-filter})\\nORDER BY c._ts\"},
\"queryRanges\":[{\"min\":\"\",\"max\":\"FF\",\"isMinInclusive\":true,\"isMaxInclusive\":false}]}"}

Sorgu sonuçlarının sayfalandırması

Sorgu istekleri , x-ms-max-item-count ve x-ms-continuation istek üst bilgileri aracılığıyla sayfalandırmayı destekler. x-ms-max-item-count üst bilgisi, sorgu yürütmesi tarafından döndürülebilecek en fazla değer sayısını belirtir. Bu değer 1 ile 1000 arasında olabilir ve varsayılan olarak 100 ile yapılandırılır.

Sorgular, yürütmenin sonuçlarından sıfırdan belirtilen maksimum x-ms-max-item-count değerine kadar döndürür. Sorgu sonucu, sorgu tarafından döndürülen gerçek belge sayısını belirten bir x-ms-item-count üst bilgisi içerir. Sorgudan alınabilecek ek sonuçlar varsa, yanıt x-ms-continuation üst bilgisi için boş olmayan bir değer içerir.

İstemciler , x-ms-continuation üst bilgisini başka bir istek olarak yankılayarak sonuçların sonraki sayfalarını getirebilir. Tüm sonuçları okumak için istemcilerin boş bir x-ms-continuation döndürülene kadar bu işlemi yinelemesi gerekir.

Cosmos DB sorgu yürütmeleri sunucu tarafında durum bilgisi yoktur ve x-ms-continuation üst bilgisi kullanılarak herhangi bir zamanda sürdürülebilir. x-ms-continuation değeri, yürütmenin ilerleme durumunu izlemek için son işlenen belge kaynak kimliğini (_rid) kullanır. Bu nedenle, belgeler silinir ve sayfaların getirilmesi arasında yeniden eklenirse, belgeler sorgu toplu işlemlerinden herhangi birinin dışında tutulabilir. Ancak , x-ms-continuation üst bilgisinin davranışı ve biçimi gelecekteki bir hizmet güncelleştirmesinde değişebilir.

Aracılığıyla paylaş