Translator إصدار 3.0
ما الجديد؟
يوفر الإصدار 3.0 من المترجم واجهة برمجة تطبيقات ويب حديثة تستند إلى JSON. فهو يحسن قابلية الاستخدام والأداء من خلال دمج الميزات الموجودة في عمليات أقل ويوفر ميزات جديدة.
- النقل الحرفي لتحويل النص بلغة واحدة من برنامج نصي إلى برنامج نصي آخر.
- الترجمة إلى لغات متعددة في طلب واحد.
- الكشف عن اللغة والترجمة والنقل الحرفي في طلب واحد.
- قاموس للبحث عن ترجمات بديلة لمصطلح ما، للعثور على ترجمات خلفية وأمثلة توضح المصطلحات المستخدمة في السياق.
- نتائج أكثر إعلامية للكشف عن اللغة.
عناوين URL الرئيسة
تتم معالجة طلبات Translator، في معظم الحالات، بواسطة مركز البيانات الأقرب إلى مكان إنشاء الطلب. إذا كان هناك فشل في مركز البيانات عند استخدام نقطة النهاية العمومية، فقد يتم توجيه الطلب خارج المنطقة الجغرافية.
لفرض معالجة الطلب داخل جغرافية معينة، استخدم نقطة النهاية الجغرافية المطلوبة. تتم معالجة جميع الطلبات بين مراكز البيانات داخل الجغرافيا.
✔️ الميزة: نص المترجم
نقطة نهاية الخدمة | طلب مركز بيانات المعالجة |
---|---|
عمومي (مستحسن):api.cognitive.microsofttranslator.com |
أقرب مركز بيانات متوفر. |
الامريكتين:api-nam.cognitive.microsofttranslator.com |
شرق الولايات المتحدة 2 • غرب الولايات المتحدة 2 |
آسيا والمحيط الهادئapi-apc.cognitive.microsofttranslator.com : |
شرق اليابان • جنوب شرق آسيا |
أوروبا (باستثناء سويسرا):api-eur.cognitive.microsofttranslator.com |
فرنسا الوسطى • غرب أوروبا |
سويسرا: لمزيد من المعلومات، راجعنقاط نهاية خدمة سويسرا. |
شمال سويسرا • غرب سويسرا |
نقاط نهاية خدمة سويسرا
يمكن للعملاء الذين لديهم مورد موجود في شمال سويسرا أو غرب سويسرا التأكد من تقديم طلبات واجهة برمجة تطبيقات النص الخاصة بهم داخل سويسرا. للتأكد من معالجة الطلبات في سويسرا، قم بإنشاء مورد المترجم في Resource region
Switzerland 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
المترجم المخصصة غير متوفرة حاليا في سويسرا.
المصادقة
اشترك في المترجم أو خدمات متعددة في خدمات 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 من التحقق من أن العميل الطالب مفوض لاستخدام المورد وإكمال الطلب.
المتطلبات المسبقه
فهم موجز لكيفية المصادقة باستخدام معرف Microsoft Entra.
فهم مختصر لكيفية تخويل الوصول إلى الهويات المدارة.
رؤوس
الرأس | القيمة |
---|---|
التصريح | القيمة هي رمز مميز لحامل الوصول تم إنشاؤه بواسطة Azure AD.
|
Ocp-Apim-Subscription-Region | القيمة هي منطقة مورد translator.
|
Ocp-Apim-ResourceId | القيمة هي معرف المورد لمثيل مورد Translator.
|
صفحة خصائص Translator—مدخل Azure
الأمثلة
استخدام نقطة النهاية العمومية
// 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 والسماح بالوصول من الشبكات المحددة ونقاط النهاية الخاصة.
انتقل إلى مورد المترجم في مدخل Microsoft Azure.
حدد Networking من قسم Resource Management .
ضمن علامة التبويب جدران الحماية والشبكات الظاهرية، اختر الشبكات المحددة ونقاط النهاية الخاصة.
حدد حفظ لتطبيق التغييرات التي أجريتها.
حدد Keys and Endpoint من قسم Resource Management .
حدد علامة التبويب Virtual Network.
يتم سرد نقاط النهاية لترجمة النص وترجمة المستندات.
الرؤوس | الوصف |
---|---|
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، ضمن قسم المقاييس كما هو موضح في لقطة الشاشة أدناه. لمزيد من المعلومات، راجع مقاييس البيانات والنظام الأساس.
يسرد هذا الجدول المقاييس المتوفرة مع وصف لكيفية استخدامها لمراقبة استدعاءات واجهة برمجة تطبيقات الترجمة.
مقاييس | الوصف |
---|---|
TotalCalls | إجمالي عدد مكالمات API. |
TotalTokenCalls | إجمالي عدد استدعاءات واجهة برمجة التطبيقات عبر خدمة الرمز المميز باستخدام رمز المصادقة المميز. |
SuccessfulCalls | عدد الاستدعاءات الناجحة. |
TotalErrors | عدد المكالمات التي بها استجابة خطأ. |
BlockedCalls | عدد الاستدعاءات التي تجاوزت الحد الأقصى للمعدل أو مساحة القرص المتوفرة. |
ServerErrors | عدد الاستدعاءات التي بها خطأ داخلي للخادم (5XX). |
ClientErrors | عدد المكالمات التي بها خطأ من جانب العميل(4XX). |
زمن الانتقال | مدة إكمال الطلب بالمللي ثانية. |
CharactersTranslated | إجمالي عدد الأحرف في طلب النص الوارد. |
الملاحظات
https://aka.ms/ContentUserFeedback.
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجعإرسال الملاحظات وعرضها المتعلقة بـ