REST API kullanarak Azure Cosmos DB kaynaklarını sorgulama

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ı

İstek Üst Bilgileri

Aşağıdaki tabloda sorgu işlemlerini gerçekleştirmek için kullanılan ortak üst bilgiler yer alı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.

İ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ı.

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.

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}  

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.

Ayrıca Bkz.

• Azure Cosmos DB
• Azure Cosmos DB SQL API
• Azure Cosmos DB SQL API SDK'ları
• .NET Örneğinden REST