Belgelerin durumunu alma
Başvuru
Hizmeti: Azure AI Belge Çevirisi
API Sürümü: v1.1
Yanıttaki belge sayısı disk belleği sınırımızı aşarsa, sunucu tarafı disk belleği kullanılır. Sayfalandırılmış yanıtlar kısmi bir sonucu gösterir ve yanıta bir devamlılık belirteci ekler. Devam belirtecinin olmaması, kullanılabilir başka sayfa olmadığı anlamına gelir.
$top, $skipve $maxpagesize sorgu parametreleri, döndürülecek sonuç sayısını ve koleksiyonun uzaklığını belirtmek için kullanılabilir.
$top kullanıcının tüm sayfalarda döndürülmek istediği toplam kayıt sayısını gösterir. $skip , belirtilen sıralama yöntemine göre sunucu tarafından tutulan belge durumu listesinden atlanacak kayıt sayısını gösterir. Varsayılan olarak, azalan başlangıç zamanına göre sıralarız. $maxpagesize bir sayfada döndürülen en fazla öğe sayısıdır. aracılığıyla $top daha fazla öğe istenirse (veya $top belirtilmezse ve döndürülecek daha fazla öğe varsa), @nextLink sonraki sayfanın bağlantısını içerir.
$orderBy sorgu parametresi, döndürülen listeyi (örn. "$orderBy=createdDateTimeUtc asc" veya "$orderBy=createdDateTimeUtc desc") sıralamak için kullanılabilir. Varsayılan sıralama, createdDateTimeUtc tarafından azalan düzendedir. Bazı sorgu parametreleri, döndürülen listeyi filtrelemek için kullanılabilir (örneğin: "status=Succeeded,Canceled") yalnızca başarılı ve iptal edilen belgeleri döndürür. createdDateTimeUtcStart ve createdDateTimeUtcEnd, döndürülen listeyi filtrelemek üzere bir tarih saat aralığı belirtmek için birlikte veya ayrı ayrı kullanılabilir. Desteklenen filtreleme sorgusu parametreleri şunlardır (status, IDs, createdDateTimeUtcStart, createdDateTimeUtcEnd).
Hem hem $skip de $top dahil edildiğinde, sunucu önce uygulamalı ve ardından $top koleksiyona uygulanmalıdır$skip.
Not
Sunucu ve/veya $skipdeğerini karşılayamazsa$top, sunucu yalnızca sorgu seçeneklerini yoksaymak yerine istemciye bu konuda bilgi veren bir hata döndürmelidir. Bu, istemcinin döndürülen veriler hakkında varsayımlarda bulunma riskini azaltır.
İstek URL’si
Şuraya bir GET isteği gönderin:
GET https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches/{id}/documents
Özel etki alanı adınızı bulmayı öğrenin.
Önemli
- Belge Çevirisi hizmetine yönelik tüm API istekleri için özel bir etki alanı uç noktası gerekir.
- Belge Çevirisi'ne HTTP isteklerinde bulunmak için Azure portalı kaynak Anahtarlar ve Uç Nokta sayfanızda bulunan uç noktayı veya genel çeviri uç noktasını
api.cognitive.microsofttranslator.comkullanamazsınız.
İstek parametreleri
Sorgu dizesinde geçirilen istek parametreleri şunlardır:
| Sorgu parametresi | İçinde | Zorunlu | Türü | Açıklama |
|---|---|---|---|---|
id |
yol | Doğru | Dize | İşlem kimliği. |
$maxpagesize |
query | False | tamsayı int32 | $maxpagesize bir sayfada döndürülen en fazla öğe sayısıdır. aracılığıyla $top daha fazla öğe istenirse (veya $top belirtilmezse ve döndürülecek daha fazla öğe varsa), @nextLink sonraki sayfanın bağlantısını içerir. İstemciler, bir tercih belirterek $maxpagesize belirli bir sayfa boyutuyla sunucu temelli disk belleği isteyebilir. Belirtilen sayfa boyutu sunucunun varsayılan sayfa boyutundan küçükse sunucu bu tercihe göre olmalıdır. |
| $orderBy | query | False | dizi | Koleksiyon için sıralama sorgusu (örn: CreatedDateTimeUtc asc, CreatedDateTimeUtc desc). |
$skip |
query | False | tamsayı int32 | $skip, belirtilen sıralama yöntemine göre sunucu tarafından tutulan kayıt listesinden atlanacak kayıt sayısını gösterir. Varsayılan olarak, azalan başlangıç zamanına göre sıralarız. İstemciler, döndürülecek sonuç sayısını ve koleksiyona uzaklığı belirtmek için $top ve $skip sorgu parametrelerini kullanabilir. İstemci hem hem $skipde $top döndürdüğünde, sunucu önce uygulamalı ve ardından $top koleksiyona uygulanmalıdır$skip. Sunucu ve/veya $skipdeğerini karşılayamazsa$top, sunucu yalnızca sorgu seçeneklerini yoksaymak yerine istemciye bu konuda bilgi veren bir hata döndürmelidir. |
$top |
query | False | tamsayı int32 | $top kullanıcının tüm sayfalarda döndürülmek istediği toplam kayıt sayısını gösterir. İstemciler döndürülecek sonuç sayısını ve $skip koleksiyona uzaklığı belirtmek için parametreleri kullanabilir $top ve sorgulayabilir. İstemci hem hem $skipde $top döndürdüğünde, sunucu önce uygulamalı ve ardından $top koleksiyona uygulanmalıdır$skip. Sunucu ve/veya $skipdeğerini karşılayamazsa$top, sunucu yalnızca sorgu seçeneklerini yoksaymak yerine istemciye bu konuda bilgi veren bir hata döndürmelidir. |
| createdDateTimeUtcEnd | query | False | dize tarih-saat | Öğeleri daha önce almak için bitiş tarihi saat. |
| createdDateTimeUtcStart | query | False | dize tarih-saat | Sonraki öğeleri almak için başlangıç tarih saati. |
ids |
query | False | dizi | Filtrelemede kullanılacak kimlikler. |
| Durum | query | False | dizi | Filtrelemede kullanılacak durumlar. |
İstek üst bilgileri
İstek üst bilgileri şunlardır:
| Üst Bilgiler | Açıklama |
|---|---|
| Ocp-Apim-Subscription-Key | Gerekli istek üst bilgisi |
Yanıt durum kodları
Bir isteğin döndürdüğü olası HTTP durum kodları aşağıdadır.
| Durum Kodu | Açıklama |
|---|---|
| 200 | Tamam. Başarılı istek ve belgelerin durumunu döndürür. HeadersRetry-After: integerETag: string |
| 400 | Geçersiz istek. Giriş parametrelerini denetleyin. |
| Kategori 401 | Yetkisiz. Kimlik bilgilerinizi denetleyin. |
| 404 | Kaynak bulunamadı. |
| 500 | İç Sunucu Hatası. |
| Diğer Durum Kodları | • Çok fazla istek • Sunucu geçici olarak kullanılamıyor |
Belgelerin durum yanıtlarını alma
Başarılı belge alma durumu yanıtı
Başarılı bir yanıtta aşağıdaki bilgiler döndürülür.
| Adı | Tür | Açıklama |
|---|---|---|
| @nextLink | Dize | Sonraki sayfanın URL'si. Başka sayfa yoksa null. |
| değer | DocumentStatus [] | Tek tek belgelerin ayrıntı durum listesi. |
| value.path | Dize | Belgenin veya klasörün konumu. |
| value.sourcePath | Dize | Kaynak belgenin konumu. |
| value.createdDateTimeUtc | Dize | İşlem oluşturma tarihi saati. |
| value.lastActionDateTimeUtc | Dize | İşlemin durumunun güncelleştirildiği tarih saati. |
| value.status | durum | İş veya belge için olası durumların listesi. • İptal Edildi •Iptal •Başarısız • Başlamadı •Çalışan •Başarılı • ValidationFailed |
| value.to | Dize | Dile. |
| value.progress | Numara | Varsa çevirinin ilerleme durumu. |
| value.id | Dize | Belge Kimliği. |
| value.characterCharged | integer | API tarafından ücretlendirilen karakterler. |
Hata yanıtı
| Adı | Tür | Açıklama |
|---|---|---|
| kod | Dize | Üst düzey hata kodları içeren sabit listeleri. Olası değerler: • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable •Yetki -siz |
| ileti | Dize | Üst düzey hata iletisi alır. |
| hedef | Dize | Hatanın kaynağını alır. Örneğin, geçersiz bir belge için veya document id olabilirdocuments. |
| innerError | InnerTranslationError | Azure AI hizmetleri API Yönergelerine uygun yeni İç Hata biçimi. Bu hata iletisi gerekli ErrorCode, ileti ve isteğe bağlı özellikler hedefi, ayrıntılar (anahtar değer çifti), iç hata (iç içe yerleştirilmiş olabilir) özelliklerini içerir. |
| innerError.code | Dize | Kod hata dizesini alır. |
| innerError.message | Dize | Üst düzey hata iletisi alır. |
| innerError.target | Dize | Hatanın kaynağını alır. Örneğin, documentsdocument id veya geçersiz bir belge varsa olabilir. |
Örnekler
Örnek başarılı yanıt
Aşağıdaki JSON nesnesi başarılı bir yanıt örneğidir.
{
"value": [
{
"path": "https://myblob.blob.core.windows.net/destinationContainer/fr/mydoc.txt",
"sourcePath": "https://myblob.blob.core.windows.net/sourceContainer/fr/mydoc.txt",
"createdDateTimeUtc": "2020-03-26T00:00:00Z",
"lastActionDateTimeUtc": "2020-03-26T01:00:00Z",
"status": "Running",
"to": "fr",
"progress": 0.1,
"id": "273622bd-835c-4946-9798-fd8f19f6bbf2",
"characterCharged": 0
}
],
"@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55/documents?$top=5&$skip=15"
}
Örnek hata yanıtı
Aşağıdaki JSON nesnesi bir hata yanıtı örneğidir. Diğer hata kodlarının şeması aynıdır.
Durum kodu: 500
{
"error": {
"code": "InternalServerError",
"message": "Internal Server Error",
"target": "Operation",
"innerError": {
"code": "InternalServerError",
"message": "Unexpected internal server error has occurred"
}
}
}
Sonraki adımlar
Belge Çevirisi ve istemci kitaplığını kullanma hakkında daha fazla bilgi edinmek için hızlı başlangıcımızı izleyin.