مشاركة عبر

الحصول على حالة لكافة المستندات

  • مقالة

ميزة المرجع
: Azure الذكاء الاصطناعي المترجم → إصدار واجهة برمجة تطبيقات ترجمة
المستندات: 2024-05-01
أسلوب HTTP: GET

هام

تتطلب جميع طلبات واجهة برمجة التطبيقات إلى ميزة ترجمة المستندات نقطة نهاية مجال مخصصة موجودة في صفحة نظرة عامة على الموارد في مدخل Microsoft Azure.

  • get documents status استخدم الأسلوب لطلب الحالة لكافة المستندات في مهمة الترجمة.

  • $top$skipيمكن استخدام معلمات الاستعلام و و $maxpagesize لتحديد عدد النتائج التي سيتم إرجاعها وإزاحة للمجموعة.

    • $top يشير إلى إجمالي عدد السجلات التي يريد المستخدم إرجاعها عبر جميع الصفحات.
    • $skip يشير إلى عدد السجلات التي يجب تخطيها من قائمة حالة المستند التي يحتفظ بها الخادم استنادا إلى طريقة الفرز المحددة. بشكل افتراضي، يتم فرز السجلات حسب وقت البدء التنازلي.
    • $maxpagesize هو الحد الأقصى للعناصر التي يتم إرجاعها في صفحة.
    • إذا تم طلب المزيد من العناصر عبر $top (أو $top لم يتم تحديدها وكان هناك المزيد من العناصر التي سيتم إرجاعها)، @nextLink فستحتوي على الارتباط إلى الصفحة التالية.
    • إذا تجاوز عدد المستندات في الاستجابة حد الترحيل الخاص بنا، يتم استخدام الترحيل من جانب الخادم.
    • تشير الردود المرقمة إلى نتيجة جزئية وتتضمن رمز استمرار في الاستجابة. يعني عدم وجود رمز استمرار عدم توفر صفحات أخرى.

إشعار

إذا تعذر على الخادم الالتزام $top و/أو $skip، فيجب على الخادم إرجاع خطأ إلى العميل لإعلامه بذلك بدلا من مجرد تجاهل خيارات الاستعلام. هذا يقلل من مخاطر قيام العميل بوضع افتراضات بشأن البيانات التي يتم إرجاعها.

  • $orderBy يمكن استخدام معلمة الاستعلام لفرز القائمة التي تم إرجاعها (على سبيل المثال: $orderBy=createdDateTimeUtc asc أو $orderBy=createdDateTimeUtc desc).
  • الفرز الافتراضي هو تنازلي حسب createdDateTimeUtc. يمكن استخدام بعض معلمات الاستعلام لتصفية القائمة التي تم إرجاعها (على سبيل المثال: status=Succeeded,Cancelled) فقط إرجاع المستندات الناجحة والملغاة.
  • createdDateTimeUtcStart يمكن استخدام معلمات الاستعلام و createdDateTimeUtcEnd معا أو بشكل منفصل لتحديد نطاق من التاريخ والوقت لتصفية القائمة التي تم إرجاعها.
  • معلمات استعلام التصفية المدعومة هي (statusو createdDateTimeUtcStartidو و).createdDateTimeUtcEnd
  • عند تضمين كل من $top و $skip ، يجب تطبيق $skip الخادم أولا ثم $top على المجموعة.

URL للطلب

إرسال طلب GET إلى:

  curl -i -X GET "{document-translation-endpoint}/translator/document/batches/{id}/documents?api-version={date}"

تحديد موقع القيمة id

  • يمكنك العثور على المهمة id في قيمة عنوان URL لاستجابة Operation-Location أسلوب POSTstart-batch-translation. السلسلة الأبجدية الرقمية التي تتبع المعلمة /document/ هي مهمة idالعملية :
رأس الاستجابة عنوان URL للاستجابة
موقع-العملية {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01

معلمات الطلب

معلمات الطلب التي تم تمريرها على سلسلة الاستعلام هي:

معلمة الاستعلام في المطلوب نوع ‏‏الوصف
id path صواب سلسلة معرف العملية.
$maxpagesize استعلام خطأ integer int32 $maxpagesize هو الحد الأقصى للعناصر التي يتم إرجاعها في صفحة. إذا تم طلب المزيد من العناصر عبر $top (أو $top لم يتم تحديدها وكان هناك المزيد من العناصر التي سيتم إرجاعها)، @nextLink فستحتوي على الارتباط إلى الصفحة التالية. يمكن للعملاء طلب الترحيل المستند إلى الخادم بحجم صفحة معين عن طريق تحديد تفضيل $maxpagesize . يجب أن يحترم الخادم هذا التفضيل إذا كان حجم الصفحة المحدد أصغر من حجم الصفحة الافتراضي للخادم.
$orderBy استعلام خطأ صفيف استعلام الفرز للمجموعة (على سبيل المثال: CreatedDateTimeUtc asc، CreatedDateTimeUtc desc).
$skip استعلام خطأ integer int32 يشير $skip إلى عدد السجلات المطلوب تخطيها من قائمة السجلات التي يحتفظ بها الخادم بناءً على طريقة الفرز المحددة. افتراضياً، نقوم بالفرز حسب وقت البدء التنازلي. يمكن للعملاء استخدام معلمات $top والاستعلام $skip لتحديد عدد النتائج التي سيتم إرجاعها وإزاحة في المجموعة. عندما يقوم العميل بإرجاع كل من $top و $skip، يجب تطبيق $skip الخادم أولا ثم $top على المجموعة. إذا تعذر على الخادم الالتزام $top و/أو $skip، يجب على الخادم إرجاع خطأ إلى العميل لإعلامه بذلك بدلا من مجرد تجاهل خيارات الاستعلام.
$top استعلام خطأ integer int32 $top يشير إلى إجمالي عدد السجلات التي يريد المستخدم إرجاعها عبر جميع الصفحات. يمكن للعملاء استخدام $top المعلمات والاستعلام $skip عنها لتحديد عدد النتائج التي سيتم إرجاعها وإزاحة في المجموعة. عندما يقوم العميل بإرجاع كل من $top و $skip، يجب تطبيق $skip الخادم أولا ثم $top على المجموعة. إذا تعذر على الخادم الالتزام $top و/أو $skip، يجب على الخادم إرجاع خطأ إلى العميل لإعلامه بذلك بدلا من مجرد تجاهل خيارات الاستعلام.
createdDateTimeUtcEnd استعلام خطأ سلسلة التاريخ والوقت تاريخ الانتهاء للحصول على العناصر من قبل.
createdDateTimeUtcStart استعلام خطأ سلسلة التاريخ والوقت وقت البدء للحصول على العناصر بعد.
ids استعلام خطأ صفيف معرفات لاستخدامها في التصفية.
statuses استعلام خطأ صفيف حالات لاستخدامها في التصفية.

عناوين الطلبات

عناوين الطلبات هي:

الرؤوس ‏‏الوصف الحالة
Ocp-Apim-Subscription-Key مفتاح واجهة برمجة تطبيقات خدمة المترجم من مدخل Microsoft Azure. المطلوب
Ocp-Apim-Subscription-Region المنطقة التي تم فيها إنشاء المورد الخاص بك. • مطلوب عند استخدام مورد إقليمي (جغرافي) مثل غرب الولايات المتحدة.
رمز نقطي.
نوع المحتوى نوع محتوى الحمولة. القيمة المقبولة هي application/json أو charset = UTF-8. • مطلوب

رموز حالة الاستجابة

فيما يلي رموز حالة HTTP المحتملة التي يعرضها الطلب.

رمز الحالة ‏‏الوصف
200 جيد. طلب ناجحة وإرجاع حالة المستندات. HeadersRetry-After: integerETag: string
400 Invalid request. تحقق من معلمات الإدخال.
401 Unauthorized. تحقق من معلومات تسجيل الدخول الخاصة بك.
404 لم يتم العثور على المورد.
500 خطأ في الخادم الداخلي.
رموز الحالة الأخرى • طلبات كثيرة جدا
• الخادم غير متوفر مؤقتا

الحصول على استجابة حالة المستندات

نجاح الحصول على استجابة حالة المستندات

يتم إرجاع المعلومات التالية في استجابة ناجحة.

Name كتابة ‏‏الوصف
@nextLink سلسلة عنوان URL للصفحة التالية. لاغية إذا لم يكن هناك المزيد من الصفحات المتاحة.
قيمة DocumentStatus [] قائمة حالة التفاصيل للمستندات الفردية.
value.path سلسلة موقع المستند أو المجلد.
value.sourcePath سلسلة موقع المستند المصدر.
value.createdDateTimeUtc سلسلة أنشأت العملية التاريخ والوقت.
value.lastActionDateTimeUtc سلسلة وقت التاريخ الذي يتم فيه تحديث حالة العملية.
value.status الحالة قائمة الحالات المُحتملة للمهمة أو المستند.
• مُلغى
•الغاء
•فشل
• لم يتم البدء
•تشغيل
•نجحت
• ValidationFailed
value.to سلسلة إلى اللغة.
value.progress رقم مدى تقدم الترجمة إذا كان متاحاً.
value.id سلسلة ⁧⁩معرّف المستند.
value.characterCharged integer الأحرف التي يتم تحصيلها من واجهة برمجة التطبيقات.

الاستجابة للخطأ

Name كتابة ‏‏الوصف
الكود سلسلة قوائم تعدادات تحتوي على رموز خطأ عالية المستوى. القيم الممكنة:
• InternalServerError
• InvalidArgument
• طلب غير صالح
• RequestRateTooHigh
• ResourceNotFound
• ServiceUnavailable
•غير المصرح به
رسالة سلسلة يحصل على رسالة خطأ عالية المستوى.
الهدف سلسلة الحصول على مصدر الخطأ. على سبيل المثال، سيكون documents مستندا غير صالح أو document id لمستند غير صالح.
innerError InnerTranslationError تنسيق خطأ داخلي جديد يتوافق مع إرشادات واجهة برمجة تطبيقات خدمات Azure الذكاء الاصطناعي. تحتوي رسالة الخطأ هذه على الخصائص المطلوبة ErrorCode والرسالة وهدف الخصائص الاختيارية والتفاصيل (زوج قيمة المفتاح) والخطأ الداخلي (يمكن تداخله).
innerError.code سلسلة يحصل على سلسلة خطأ في التعليمة البرمجية.
innerError.message سلسلة يحصل على رسالة خطأ عالية المستوى.
innerError.target سلسلة الحصول على مصدر الخطأ. على سبيل المثال، سيكون documents أو document id إذا كان هناك مستند غير صالح.

الأمثلة

تلميح

استخدم هذا الأسلوب لاسترداد المعلمة documentIdلسلسلة استعلام الحصول على حالة المستند.

مثال على الاستجابة الناجحة

عنصر JSON التالي هو مثال على استجابة ناجحة.

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

مثال على استجابة الخطأ

عنصر JSON التالي هو مثال على الاستجابة للخطأ. مخطط رموز الخطأ الأخرى هو نفسه.

رمز الحالة: 500

{
  "error": {
    "code": "InternalServerError",
    "message": "Internal Server Error",
    "target": "Operation",
    "innerError": {
      "code": "InternalServerError",
      "message": "Unexpected internal server error has occurred"
    }
  }
}

الخطوات التالية

اتبع خطواتنا السريعة لمعرفة المزيد بشأن استخدام ترجمة المستندات ومكتبة العميل.

البدء في استخدام Document Translation