الهويات المدارة لـ Document Translation

مقالة
02/12/2024

الهويات المدارة لموارد Azure هي أساسيات الخدمة التي تنشئ هوية Microsoft Entra وأذونات محددة لموارد Azure المدارة. الهويات المدارة هي طريقة أكثر أمانا لمنح الوصول إلى بيانات التخزين واستبدال متطلبات تضمين الرموز المميزة لتوقيع الوصول المشترك (SAS) بعناوين URL المصدر والهدف.

Screenshot of managed identity flow (RBAC).

يمكنك استخدام الهويات المدارة لمنح حق الوصول إلى أي مورد يدعم مصادقة Microsoft Entra، بما في ذلك التطبيقات الخاصة بك.
لمنح حق الوصول إلى مورد Azure، قم بتعيين دور Azure إلى هوية مدارة باستخدام التحكم في الوصول المستند إلى دور Azure (Azure RBAC).
ولا توجد تكلفة إضافية لاستخدام الهويات المدارة في Azure.

هام

عند استخدام الهويات المُدارة، لا تقم بتضمين عنوان URL لرمز SAS مع طلبات HTTP - ستفشل طلباتك. يحل استخدام الهويات المدارة محل متطلبات تضمين الرموز المميزة لتوقيع الوصول المشترك (SAS) مع عناوين URL المصدر والهدف.
لاستخدام الهويات المدارة لعمليات ترجمة المستندات، يجب إنشاء مورد المترجم في منطقة Azure جغرافية معينة مثل شرق الولايات المتحدة. إذا تم تعيين منطقة موارد المترجم إلى عمومي، فلا يمكنك استخدام الهوية المدارة لترجمة المستندات. لا يزال بإمكانك استخدام الرموز المميزة لتوقيع الوصول المشترك (SAS) لترجمة المستندات.
تتوفر Document Translation فقط في خطة الخدمة القياسية S1 (الدفع عند التنقل) أو في خطة خصم حجم D3. راجعتسعير خدمات Azure الذكاء الاصطناعي - المترجم.

المتطلبات الأساسية

لبدء الاستخدام، تحتاج إلى ما يلي:

حساب Azure نشط- إذا لم يكن لديك حساب، فيمكنك إنشاء حساب مجاني.
مورد المترجم خدمة واحدة (وليس خدمات Azure الذكاء الاصطناعي متعددة الخدمات) تم تعيينه لمنطقة جغرافية مثل غرب الولايات المتحدة. للحصول على خطوات مفصلة، راجعإنشاء مورد متعدد الخدمات.
فهم موجز للتحكم في الوصول استنادا إلى الدور في Azure (Azure RBAC) باستخدام مدخل Microsoft Azure.
حساب Azure Blob Storage في نفس المنطقة مثل مورد المترجم. تحتاج أيضا إلى إنشاء حاويات لتخزين بيانات الكائن الثنائي كبير الحجم وتنظيمها داخل حساب التخزين الخاص بك.
إذا كان حساب التخزين الخاص بك خلف جدار حماية، يجب تمكين التكوين التالي:
1. انتقل إلى مدخل Azure ثم قم بتسجيل الدخول إلى حساب Azure الخاص بك.
2. حدد حساب التخزين.
3. في مجموعة Security + networking في الجزء الأيمن، حدد Networking.
4. في علامة التبويب Firewalls and virtual networks ، حدد Enabled من الشبكات الظاهرية المحددة وعناوين IP.
5. إلغاء تحديد جميع خانات الاختيار.
6. تأكد من تحديد توجيه شبكة Microsoft.
7. ضمن قسم Resource instances، حدد Microsoft.CognitiveServices/accounts كنوع المورد وحدد مورد المترجم كاسم المثيل.
8. تأكد من تحديد خانة الاختيار السماح لخدمات Azure في قائمة الخدمات الموثوق بها بالوصول إلى حساب التخزين هذا. لمزيد من المعلومات حول إدارة الاستثناءات، راجعتكوين جدران حماية Azure Storage والشبكات الظاهرية.
9. حدد حفظ.
  
  إشعار
  
  قد يستغرق نشر تغييرات الشبكة ما يصل إلى 5 دقائق.
على الرغم من أن الوصول إلى الشبكة مسموح به الآن، لا يزال مورد المترجم غير قادر على الوصول إلى البيانات في حساب التخزين الخاص بك. تحتاج إلى إنشاء هوية مدارة وتعيين دور وصول محدد إلى مورد المترجم الخاص بك.

إدارة تخصيصات الهوية

هناك نوعان من الهويات المدارة: مخصص من قِبَل النظام ومخصص من قِبَل المستخدم. حالياً، تدعم Document Translation الهوية المُدارة المعينة من قِبل النظام:

يتم تمكين الهوية المُدارة المعينة من النظام مباشرة على مثيل الخدمة. لا يتم تمكينها افتراضياً؛ يجب عليك الذهاب إلى الموارد الخاصة بك وتحديث إعداد الهوية.
ترتبط الهوية المُدارة المعينة من قِبَل النظام بالمورد الخاص بك طوال دورة حياته. إذا قمت بحذف المورد الخاص بك، يتم حذف الهوية المدارة أيضا.

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

تمكين هوية مُدارة مخصصة من قبل النظام

يجب منح المترجم وصول المورد إلى حساب التخزين الخاص بك قبل أن يتمكن من إنشاء الكائنات الثنائية كبيرة الحجم أو قراءتها أو حذفها. بمجرد تمكين مورد المترجم بهوية مدارة معينة من قبل النظام، يمكنك استخدام التحكم في الوصول المستند إلى دور Azure (Azure RBAC)، لمنح المترجم الوصول إلى حاويات تخزين Azure.

انتقل إلى مدخل Azure ثم قم بتسجيل الدخول إلى حساب Azure الخاص بك.
حدد مورد المترجم.
في مجموعة Resource Management في الجزء الأيمن، حدد Identity.
ضمن علامة التبويب تعيين النظام، قم بتشغيل تبديل الحالة.

هام

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

منح حق الوصول إلى حساب التخزين لمورد المترجم

هام

لتعيين دور هوية مدارة يعينها النظام، تحتاج إلى أذونات Microsoft.Authorization/roleAssignments/write، مثل المالك أو وصول المستخدم مسؤول istrator في نطاق التخزين لمورد التخزين.

انتقل إلى مدخل Azure ثم قم بتسجيل الدخول إلى حساب Azure الخاص بك.
حدد مورد المترجم.
في مجموعة Resource Management في الجزء الأيمن، حدد Identity.
ضمن Permissions، حدد Azure role assignments:
في صفحة تعيينات دور Azure التي تم فتحها، اختر اشتراكك من القائمة المنسدلة ثم حدد + إضافة تعيين دور.

بعد ذلك، قم بتعيين دور Storage Blob Data Contributor إلى مورد خدمة المترجم. يمنح الدور Storage Blob Data Contributor للمترجم (الذي يمثله الهوية المُدارة المعينة من قِبَل النظام) حق الوصول للقراءة والكتابة والحذف إلى حاوية البيانات الثنائية الكبيرة والبيانات. في النافذة المنبثقة Add role assignment، أكمل الحقول كما يلي وحدد Save:

الحقل	القيمة
النطاق	*التخزين*.
الاشتراك	*الاشتراك المرتبط بمورد التخزين الخاص بك*.
المورد	*اسم مورد التخزين الخاص بك*.
الدور	*تخزين بيانات Blob المساهم*.

Screenshot: add role assignments page in the Azure portal.

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

طلبات HTTP

يتم إرسال طلب ترجمة دفعية غير متزامن إلى نقطة نهاية خدمة المترجم عبر طلب POST.
مع الهوية المدارة و Azure RBAC، لم تعد بحاجة إلى تضمين عناوين URL ل SAS.
إذا نجحت، يقوم أسلوب POST بإرجاع 202 Accepted رمز استجابة وتنشئ الخدمة طلب دفعة.
تظهر المستندات المترجمة في الحاوية الهدف.

الرؤوس

يتم تضمين الرؤوس التالية مع كل طلب Document Translation API:

رأس HTTP	‏‏الوصف
Ocp-Apim-Subscription-Key	مطلوب: القيمة هي مفتاح Azure لمورد خدمات المترجم أو Azure الذكاء الاصطناعي.
نوع المحتوى	مطلوب: تحديد نوع محتوى البيانات الفعلية. القيم المقبولة هي application/json or charset=UTF-8.

نص طلب POST

عنوان URL للطلب هو POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
نص الطلب هو عنصر JSON يسمى inputs.
inputsيحتوي الكائن على كل من sourceURL وtargetURL وعناوين حاوية لأزواج اللغة المصدر والهدف. باستخدام الهوية المدارة المعينة من قبل النظام، يمكنك استخدام عنوان URL لحساب التخزين العادي (بدون SAS أو إضافات أخرى). التنسيق هو https://<storage_account_name>.blob.core.windows.net/<container_name>.
prefixيتم suffix استخدام الحقلين (اختياري) لتصفية المستندات في الحاوية بما في ذلك المجلدات.
يتم تطبيق قيمة للحقل glossaries (اختياري) عند ترجمة المستند.
targetUrlيجب أن تكون لغة لكل هدف فريدة من نوعها.

هام

إذا كان ملف يحمل نفس الاسم موجودًا بالفعل في الوجهة، ستفشل المهمة. عند استخدام الهويات المدارة، لا تقم بتضمين عنوان URL للرمز المميز SAS مع طلبات HTTP الخاصة بك. إذا قمت بذلك، ستفشل طلباتك.

ترجمة جميع المستندات في حاوية

يشير نص طلب العينة هذا إلى حاوية مصدر لكافة المستندات المراد ترجمتها إلى لغة مستهدفة.

لمزيد من المعلومات، راجعمعلمات الطلب.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>"
                    "language": "fr"
                }
            ]
        }
    ]
}

ترجمة مستند معين في حاوية

يشير نص طلب العينة هذا إلى مستند مصدر واحد لترجمته إلى لغتين مستهدفتين.

هام

بالإضافة إلى معلمات الطلب المذكورة سابقا، يجب تضمين "storageType": "File". خلاف ذلك، يفترض أن يكون عنوان URL المصدر على مستوى الحاوية.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

ترجمة كافة المستندات في حاوية باستخدام مسرد مخصص

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

لمزيد من المعلومات، راجعمعلمات الطلب.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://<storage_account_name>.blob.core.windows.net/<glossary_container_name>/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

رائع! لقد تعلمت للتو كيفية تمكين واستخدام هوية مدارة معينة من قبل النظام. باستخدام الهوية المدارة لموارد Azure وAzure RBAC، منحت المترجم حقوق وصول محددة لمورد التخزين الخاص بك دون تضمين رموز SAS المميزة مع طلبات HTTP الخاصة بك.

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

التشغيل السريع: بدء استخدام ترجمة المستندات

البرنامج التعليمي: الوصول إلى Azure Storage من تطبيق ويب باستخدام الهويات المدارة

Share via