Translator إصدار 3.0

  • مقالة

ما الجديد؟

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

  • النقل الحرفي لتحويل النص بلغة واحدة من برنامج نصي إلى برنامج نصي آخر.
  • الترجمة إلى لغات متعددة في طلب واحد.
  • الكشف عن اللغة والترجمة والنقل الحرفي في طلب واحد.
  • قاموس للبحث عن ترجمات بديلة لمصطلح ما، للعثور على ترجمات خلفية وأمثلة توضح المصطلحات المستخدمة في السياق.
  • نتائج أكثر إعلامية للكشف عن اللغة.

عناوين URL الرئيسة

تتم معالجة طلبات Translator، في معظم الحالات، بواسطة مركز البيانات الأقرب إلى مكان إنشاء الطلب. إذا كان هناك فشل في مركز البيانات عند استخدام نقطة النهاية العمومية، فقد يتم توجيه الطلب خارج المنطقة الجغرافية.

لفرض معالجة الطلب داخل جغرافية معينة، استخدم نقطة النهاية الجغرافية المطلوبة. تتم معالجة جميع الطلبات بين مراكز البيانات داخل الجغرافيا.

الموقع الجغرافي عنوان URL الأساس (نقطة نهاية جغرافية) مراكز البيانات
عمومي (non-regional) api.cognitive.microsofttranslator.com أقرب مركز بيانات متوفر
آسيا/المحيط الهادئ api-apc.cognitive.microsofttranslator.com منطقة جنوب كوريا الجنوبية، وشرق اليابان، وجنوب شرق آسيا، وشرق أستراليا
‏‏أوروبا api-eur.cognitive.microsofttranslator.com شمال أوروبا، غرب أوروبا
الولايات المتحدة api-nam.cognitive.microsofttranslator.com شرق الولايات المتحدة وجنوب وسط الولايات المتحدة وغرب وسط الولايات المتحدة وغرب الولايات المتحدة 2

1 يمكن للعملاء الذين لديهم مورد موجود في شمال سويسرا أو غرب سويسرا التأكد من تقديم طلبات واجهة برمجة تطبيقات النص الخاصة بهم داخل سويسرا. للتأكد من معالجة الطلبات في سويسرا، قم بإنشاء مورد المترجم في Resource regionSwitzerland North أو Switzerland West، ثم استخدم نقطة النهاية المخصصة للمورد في طلبات واجهة برمجة التطبيقات الخاصة بك.

على سبيل المثال: إذا قمت بإنشاء مورد المترجم في مدخل Microsoft Azure باستخدام Resource region as Switzerland North واسم المورد الخاص بك هو my-swiss-n، فإن نقطة النهاية المخصصة هي https​://my-swiss-n.cognitiveservices.azure.com. وطلب عينة للترجمة هو:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

2المترجم المخصصة غير متوفرة حاليا في سويسرا.

المصادقة

اشترك في المترجم أو خدمات متعددة في خدمات Azure الذكاء الاصطناعي، واستخدم مفتاحك (متوفر في مدخل Microsoft Azure) للمصادقة.

هناك ثلاثة عناوين يمكنك استخدامها لمصادقة اشتراكك. يصف هذا الجدول كيفية استخدام كل منها:

الرؤوس ‏‏الوصف
Ocp-Apim-Subscription-Key استخدم مع اشتراك خدمات azure الذكاء الاصطناعي إذا كنت تمرر مفتاحك السري.
القيمة هي مفتاح Azure السري لاشتراكك في Translator.
التفويض استخدم مع اشتراك خدمات Azure الذكاء الاصطناعي إذا كنت تمرر رمز مصادقة مميزا.
القيمة هي الرمز المميز للحامل: Bearer <token>.
Ocp-Apim-Subscription-Region يستخدم مع مورد مترجم متعدد الخدمات والإقليمي.
القيمة هي منطقة مورد translator متعدد الخدمات أو الإقليمي. هذه القيمة اختيارية عند استخدام مورد translator عام.

المفتاح السري

الخيار الأول هو المصادقة باستخدام Ocp-Apim-Subscription-Key العنوان. أضف Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> العنوان إلى طلبك.

المصادقة باستخدام مورد عمومي

عند استخدام مورد translator عام، تحتاج إلى تضمين عنوان واحد للاتصال بـ Translator.

الرؤوس ‏‏الوصف
Ocp-Apim-Subscription-Key القيمة هي مفتاح Azure السري لاشتراكك في Translator.

فيما يلي مثال لطلب استدعاء translator باستخدام مورد Translator العام

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

المصادقة باستخدام مورد إقليمي

عند استخدام مورد مترجم إقليمي، هناك عنوانان تحتاج إلى استدعاء المترجم.

الرؤوس ‏‏الوصف
Ocp-Apim-Subscription-Key القيمة هي مفتاح Azure السري لاشتراكك في Translator.
Ocp-Apim-Subscription-Region القيمة هي منطقة مورد translator.

فيما يلي مثال لطلب استدعاء Translator باستخدام مورد translator الإقليمي

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

المصادقة باستخدام مورد متعدد الخدمات

يسمح لك مورد متعدد الخدمات باستخدام مفتاح API واحد لمصادقة طلبات خدمات متعددة.

عند استخدام مفتاح سري متعدد الخدمات، يجب تضمين عنواني مصادقة مع طلبك. يوجد عنوانان يحتاجان إلى الاتصال بـ Translator.

الرؤوس ‏‏الوصف
Ocp-Apim-Subscription-Key القيمة هي مفتاح Azure السري لمورد متعدد الخدمات.
Ocp-Apim-Subscription-Region القيمة هي منطقة المورد متعدد الخدمات.

المنطقة مطلوبة لاشتراك واجهة برمجة تطبيقات النص متعدد الخدمات. المنطقة التي تحددها هي المنطقة الوحيدة التي يمكنك استخدامها لترجمة النص عند استخدام المفتاح متعدد الخدمات. يجب أن تكون نفس المنطقة التي حددتها عند التسجيل في اشتراكك متعدد الخدمات من خلال مدخل Microsoft Azure.

إذا قمت بتمرير المفتاح السري في سلسلة الاستعلام مع المعلمةSubscription-Key، يجب عليك تحديد المنطقة مع معلمة Subscription-Regionالاستعلام.

المصادقة باستخدام رمز مميز للوصول

بدلاً من ذلك، يمكنك استبدال مفتاحك السري برمز مميز للوصول. يتم تضمين هذا الرمز المميز مع كل طلب كعنوان Authorization. للحصول على رمز مميز للتخويل، قم بإجراء POST طلب إلى عنوان URL التالي:

نوع المورد عنوان URL لخدمة المصادقة
عمومي https://api.cognitive.microsoft.com/sts/v1.0/issueToken
إقليمي أو متعدد الخدمات https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

فيما يلي أمثلة على طلبات الحصول على رمز مميز معين مفتاح سري لمورد عمومي:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

وفيما يلي أمثلة على طلبات الحصول على رمز مميز نظرًا إلى مفتاح سري لمورد إقليمي موجود في وسط الولايات المتحدة:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

يرجع الطلب الناجح رمز الوصول المشفر كنص عادي في نص الاستجابة. يتم تمرير الرمز المميز الصالح إلى خدمة Translator كرمز مميز للحامل في التخويل.

Authorization: Bearer <Base64-access_token>

الرمز المميز للمصادقة صالح لمدة 10 دقائق. يجب إعادة استخدام الرمز المميز عند إجراء مكالمات متعددة إلى Translator. ومع ذلك، إذا كان برنامجك يقدم طلبات إلى Translator على مدى فترة زمنية طويلة، يجب على البرنامج طلب رمز وصول جديد على فترات منتظمة (على سبيل المثال، كل 8 دقائق).

المصادقة باستخدام معرف Microsoft Entra

يدعم المترجم v3.0 مصادقة Microsoft Entra والهوية المستندة إلى السحابة وحل إدارة الوصول من Microsoft. تمكّن رؤوس التخويل خدمة Translator من التحقق من أن العميل الطالب مفوض لاستخدام المورد وإكمال الطلب.

المتطلبات المسبقه

رؤوس

عنوان القيمة‬
التصريح القيمة هي رمز مميز لحامل الوصول تم إنشاؤه بواسطة Azure AD.
  • يوفر الرمز المميز للحامل إثبات المصادقة ويتحقق من صحة تخويل العميل لاستخدام المورد.
  • رمز المصادقة صالح لمدة 10 دقائق ويجب إعادة استخدامه عند إجراء مكالمات متعددة إلى Translator.
    • راجعنموذج الطلب: 2. الحصول على رمز مميز
Ocp-Apim-Subscription-Region القيمة هي منطقة مورد translator.
  • هذه القيمة اختيارية إذا كان المورد عموميًا.
Ocp-Apim-ResourceId القيمة هي معرف المورد لمثيل مورد Translator.
  • يمكنك العثور على معرف المورد في مدخل Microsoft Azure في المترجم Resource → Properties.
  • تنسيق معرف المورد:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/
صفحة خصائص Translator—مدخل Azure

Screenshot:Translator properties page in the Azure portal.

الأمثلة

استخدام نقطة النهاية العمومية

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

استخدام نقطة النهاية المخصصة

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

أمثلة باستخدام الهويات المدارة

يدعم Translator إصدار 3.0 أيضًا تفويض الوصول إلى الهويات المدارة. إذا تم تمكين هوية مُدارة لمورد translator، يمكنك تمرير رمز الحامل الذي تم إنشاؤه بواسطة هوية مُدارة في رأس الطلب.

استخدام نقطة النهاية العمومية

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

استخدام نقطة النهاية المخصصة

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

دعم الشبكة الظاهرية

خدمة Translator متاحة الآن مع قدرات الشبكة الافتراضية (VNET) في جميع مناطق سحابة Azure العامة. لتمكين الشبكة الظاهرية، راجعتكوين الشبكات الظاهرية لخدمات Azure الذكاء الاصطناعي.

بمجرد تشغيل هذه الإمكانية، يجب استخدام نقطة النهاية المخصصة للاتصال بـ Translator. لا يمكنك استخدام نقطة نهاية translator العامة ("api.cognitive.microsofttranslator.com") ولا يمكنك المصادقة باستخدام رمز مميز للوصول.

يمكنك العثور على نقطة النهاية المخصصة بعد إنشاء مورد translator والسماح بالوصول من الشبكات المحددة ونقاط النهاية الخاصة.

  1. انتقل إلى مورد المترجم في مدخل Microsoft Azure.

  2. حدد Networking من قسم Resource Management .

  3. ضمن علامة التبويب جدران الحماية والشبكات الظاهرية، اختر الشبكات المحددة ونقاط النهاية الخاصة.

    Screenshot of the virtual network setting in the Azure portal.

  4. حدد حفظ لتطبيق التغييرات التي أجريتها.

  5. حدد Keys and Endpoint من قسم Resource Management .

  6. حدد علامة التبويب Virtual Network.

  7. يتم سرد نقاط النهاية لترجمة النص وترجمة المستندات.

    Screenshot of the virtual network endpoint.

الرؤوس ‏‏الوصف
Ocp-Apim-Subscription-Key القيمة هي مفتاح Azure السري لاشتراكك في Translator.
Ocp-Apim-Subscription-Region القيمة هي منطقة مورد translator. هذه القيمة اختيارية إذا كان المورد global

فيما يلي مثال لطلب استدعاء Translator باستخدام نقطة النهاية المخصصة

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Errors

الاستجابة المعيارية للخطأ هي كائن JSON باسم زوج القيمة / الاسمerror. القيمة هي أيضًا كائن JSON مع خصائص:

  • code: رمز خطأ معرف من قبل الخادم.
  • message: سلسلة تعطي تمثيلاً قابلاً للقراءة البشرية للخطأ.

على سبيل المثال، سيتلقى العميل الذي لديه اشتراك تجريبي مجاني الخطأ التالي بمجرد استنفاد الحصة النسبية المجانية:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

رمز الخطأ هو رقم مكون من 6 أرقام يجمع بين رمز حالة HTTP المكون من 3 أرقام متبوعًا برقم مكون من 3 أرقام لتصنيف الخطأ بشكل أكبر. رموز الخطأ الشائعة هي:

الرمز ‏‏الوصف
400000 أحد إدخالات الطلب غير صالح.
400001 معلمة "النطاق" غير صالحة.
400002 المعلمة "الفئة" غير صالحة.
400003 محدد اللغة مفقود أو غير صالح.
400004 محدد البرنامج النصي الهدف ("إلى البرنامج النصي") مفقود أو غير صالح.
400005 نص الإدخال مفقود أو غير صالح.
400006 الجمع بين اللغة والبرنامج النصي غير صحيح.
400018 محدد البرنامج النصي المصدر ("من البرنامج النصي") مفقود أو غير صالح.
400019 إحدى اللغات المحددة غير مدعومة.
400020 أحد العناصر في صفيف نص الإدخال غير صحيح.
400021 معلمة إصدار واجهة برمجة التطبيقات مفقودة أو غير صالحة.
400023 أحد الزوجين اللغويين المحددين غير صالح.
400035 اللغة المصدر (حقل "من") غير صحيحة.
400036 اللغة الهدف (حقل "إلى") مفقودة أو غير صحيحة.
400042 أحد الخيارات المحددة (حقل "خيارات") غير صحيح.
400043 معرف تتبع العميل (حقل ClientTraceId أو رأس X-ClientTranceId) مفقود أو غير صالح.
400050 نص الإدخال طويل جدًا. عرض حدود الطلب.
400064 معلمة "الترجمة" مفقودة أو غير صالحة.
400070 لا يتطابق عدد البرامج النصية الهدف (معلمة ToScript) مع عدد اللغات المستهدفة (معلمة إلى).
400071 القيمة غير صالحة لـ TextType.
400072 يحتوي صفيف نص الإدخال على عناصر كثيرة جدًا.
400073 معلمة البرنامج النصي غير صالحة.
400074 نص الطلب غير صالح JSON.
400075 زوج اللغة ومجموعة الفئات غير صحيحين.
400077 تم تجاوز الحد الأقصى لحجم الطلب. عرض حدود الطلب.
400079 النظام المخصص المطلوب للترجمة بين وإلى اللغة غير موجود.
400080 النقل الحرفي غير مدعوم للغة أو النص البرمجي.
401000 الطلب غير مصرح به لأن بيانات الاعتماد مفقودة أو غير صالحة.
401015 "بيانات الاعتماد المتوفرة هي لواجهة برمجة تطبيقات الكلام. يتطلب هذا الطلب بيانات اعتماد لواجهة برمجة تطبيقات النص. استخدم اشتراكًا في Translator."
403000 العملية غير مسموح بها.
403001 العملية غير مسموح بها لأن الاشتراك قد تجاوز حصته المجانية.
405000 أسلوب الطلب غير مدعوم للمورد المطلوب.
408001 ويجري إعداد نظام الترجمة المطلوب. أعد المحاولة بعد بضع دقائق.
408002 انتهت مهلة الطلب في انتظار التدفق الوارد. لم ينتج العميل طلبا في الوقت الذي كان فيه الخادم مستعدا للانتظار. يجوز للعميل تكرار الطلب دون تعديلات في أي وقت لاحق.
415000 رأس نوع المحتوى مفقود أو غير صحيح.
429000, 429001, 429002 رفض الخادم الطلب لأن العميل تجاوز حدود الطلب.
500000 حدث خطأ غير متوقع. إذا استمر الخطأ، فقم بالإبلاغ عنه مع تاريخ / وقت الخطأ، واطلب معرفًا من عنوان الاستجابة X-RequestId، ومعرف العميل من عنوان الطلب X-ClientTraceId.
503000 الخدمة غير متوفرة مؤقتا. أعد المحاولة. إذا استمر الخطأ، فقم بالإبلاغ عنه مع تاريخ / وقت الخطأ، واطلب معرفًا من عنوان الاستجابة X-RequestId، ومعرف العميل من عنوان الطلب X-ClientTraceId.

المقاييس

تسمح لك المقاييس بعرض معلومات استخدام translator وتوافره في مدخل Azure، ضمن قسم المقاييس كما هو موضح في لقطة الشاشة أدناه. لمزيد من المعلومات، راجع مقاييس البيانات والنظام الأساس.

Translator Metrics

يسرد هذا الجدول المقاييس المتوفرة مع وصف لكيفية استخدامها لمراقبة استدعاءات واجهة برمجة تطبيقات الترجمة.

مقاييس ‏‏الوصف
TotalCalls إجمالي عدد مكالمات API.
TotalTokenCalls إجمالي عدد استدعاءات واجهة برمجة التطبيقات عبر خدمة الرمز المميز باستخدام رمز المصادقة المميز.
SuccessfulCalls عدد الاستدعاءات الناجحة.
TotalErrors عدد المكالمات التي بها استجابة خطأ.
BlockedCalls عدد الاستدعاءات التي تجاوزت الحد الأقصى للمعدل أو مساحة القرص المتوفرة.
ServerErrors عدد الاستدعاءات التي بها خطأ داخلي للخادم (5XX).
ClientErrors عدد المكالمات التي بها خطأ من جانب العميل(4XX).
زمن الانتقال مدة إكمال الطلب بالمللي ثانية.
CharactersTranslated إجمالي عدد الأحرف في طلب النص الوارد.