مثال على البرامج النصية PowerShell

  • مقالة

توفر خدمةAzure Remote Rendering واجهات برمجة تطبيقي REST التاليين:

يحتوي مستودع عينات خدمةAzure Remote Rendering على نماذج البرامج النصية في مجلد البرامج النصية للتفاعل مع واجهات برمجة التطبيقات REST للخدمة. توضح هذه المقالة استخدامها.

تلميح

هناك أيضًا أداة تستند إلى واجهة المستخدم تسمى ARRT للتفاعل مع الخدمة، وهي بديل مناسب لاستخدام البرامج النصية.

تنبيه

استدعاء وظائف API REST بشكل متكرر جدًا سيؤدي بالخادم للاندفاع بسرعة ثم الرجوع لحالة الفشل في النهاية. فشل معرف التعليمة البرمجية http في هذه الحالة هو 429 ("طلبات كثيرة جداً"). وكقاعدة عامة، يجب أن يكون هناك تأخير من 5-10 ثوانٍ بين المكالمات اللاحقة.

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

لتنفيذ نماذج البرامج النصية، تحتاج إلى إعداد وظيفي لبرنامج Azure PowerShell.

  1. تثبيت برنامج PowerShell من Azure:

    1. افتح نافذة PowerShell بحقوق وصلاحيات المسؤول.
    2. تشغيل: Install-Module -Name Az -AllowClobber

  2. إذا كنت تواجه أخطاء حول تشغيل البرامج النصية، فتأكد من أن سياسة التنفيذ الخاصة بك تم ضبطها بشكل مناسب:

    1. افتح نافذة PowerShell بحقوق وصلاحيات المسؤول.
    2. تشغيل: Set-ExecutionPolicy -ExecutionPolicy Unrestricted

  3. أنشئ حساب تخزين في Azure

  4. سجل الدخول إلى اشتراكك الذي يحتوي على حساب Azure Remote Rendering الخاص بك:

    1. افتح نافذة PowerShell.
    2. شغلConnect-AzAccount: اتبع الإرشادات التي تظهر على الشاشة.

    ملاحظة

    في حالة وجود أكثر من اشتراك واحد في مؤسستك، قد تحتاج إلى تحديد هوية الاشتراك ومناقشات المستأجر. البحث عن التفاصيل في وثائق الربط بـ -حساب Azz.

  5. تحميل مجلد البرامج النصية من مستودع خدمة Azure Remote Rendering GitHub.

ملف التكوين

بجانب .ps1 الملفات هناك أجزاء arrconfig.json تحتاج إلى ملئها:

{
    "accountSettings": {
        "arrAccountId": "<fill in the account ID from the Azure Portal>",
        "arrAccountKey": "<fill in the account key from the Azure Portal>",
        "arrAccountDomain": "<select from available regions: australiaeast, eastus, eastus2, japaneast, northeurope, southcentralus, southeastasia, uksouth, westeurope, westus2 or specify the full url>"
    },
    "renderingSessionSettings": {
        "remoteRenderingDomain": "<select from available regions: australiaeast, eastus, eastus2, japaneast, northeurope, southcentralus, southeastasia, uksouth, westeurope, westus2 or specify the full url>",
        "vmSize": "<select standard or premium>",
        "maxLeaseTime": "<hh:mm:ss>"
    },
  "assetConversionSettings": {
    "resourceGroup": "<resource group which contains the storage account you created, only needed when uploading or generating SAS>",
    "storageAccountName": "<name of the storage account you created>",
    "blobInputContainerName": "<input container inside the storage container>",
    "blobOutputContainerName": "<output container inside the storage container>",
    "localAssetDirectoryPath": "<fill in a path to a local directory containing your asset (and files referenced from it like textures)>",
    "inputFolderPath": "<optional: base folderpath in the input container for asset upload. uses / as dir separator>",
    "inputAssetPath": "<the path to the asset under inputcontainer/inputfolderpath pointing to the input asset e.g. box.fbx>",
    "outputFolderPath": "<optional: base folderpath in the output container - the converted asset and log files will be placed here>",
    "outputAssetFileName": "<optional: filename for the converted asset, this will be placed in the output container under the outputpath>"
  }
}

تنبيه

تأكد من إلغاء الخطوط المائلة العكسية بشكل صحيح في مسار LocalAssetDirectoryPath باستخدام خط مائل مزدوج: "\\" واستخدم الشرطة المائلة للأمام "/" في جميع المسارات الأخرى مثل inputFolderPath وinputAssetPath.

تنبيه

يجب تعبئة القيم الاختيارية أو ستتوجب عليك إزالة المفتاح والقيمة تمامًا. على سبيل المثال، إذا لم تستخدم المعلمة "outputAssetFileName" ، فستحتاج إلى حذف السطر بأكمله داخل arrconfig.json.

إعدادات الحساب

من أجل arrAccountId وarrAccountKey اطلع على إنشاء حساب خدمةAzure Remote Rendering arrAccountDomain يجب أن تكون منطقة من قائمة المناطق المتاحة.

إعدادات جلسة العرض

هذه البنية يجب تعبئتها إذا كنت ترغب في تشغيل RenderingSession.ps1:

  • vmSize: اختر حجم الجهاز الظاهري. الاختيار ما بين معياري أو ممتاز. إيقاف جلسات العرض عندما لا تحتاج إليها بعد الآن.
  • maxLeaseTime: المدة التي تريد تأجير الجهاز الظاهري لها. يتم إيقاف تشغيل الجهاز الظاهري عند انتهاء صلاحية عقد الإيجار. يمكن تمديد وقت الإيجار لاحقا (انظر هنا).
  • remoteRenderingDomain: المنطقة التي يوجد بها الجهاز الظاهري للعرض عن بعد.

ضبط تحويل الأصول

هذه البنية يجب تعبئتها إذا كنت ترغب في تشغيل RenderingSession.ps1.

لمزيد من التفاصيل، راجع إعداد حساب التخزين في Azure .

البرنامج النصي: RenderingSession.ps1

يتم استخدام هذا البرنامج النصي لإنشاء جلسات عمل والاستعلام عنها وإيقافها.

هام

تأكد من تعبئة الأقسام ضبط الحساب ووإعدادات جلسة العرض renderingSessionSettings في arrconfig.json.

إنشاء جلسة عرض

الاستخدام العادي مع arrconfig.js مملوء بالكامل على:

.\RenderingSession.ps1

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

لاستخدام ملف تهيئة بديلة:

.\RenderingSession.ps1 -ConfigFile D:\arr\myotherconfigFile.json

يمكنك تجاوز الإعدادات الفردية من ملف التهيئة:

.\RenderingSession.ps1 -ArrAccountDomain <arrAccountDomain> -RemoteRenderingDomain <remoteRenderingDomain> -VmSize <vmsize> -MaxLeaseTime <hh:mm:ss>

لبدء جلسة عمل فقطبدون الاقتراع، يمكنك استخدام:

.\RenderingSession.ps1 -CreateSession

هوية الجلسة التي يستردها البرنامج النصي ويجب أن يتم تمريرها إلى معظم أوامر جلسة العمل الأخرى.

استرداد خصائص جلسة العمل

للحصول على خصائص جلسة عمل، قم بتشغيل:

.\RenderingSession.ps1 -GetSessionProperties -Id <sessionID> [-Poll]

يستخدم -Poll للانتظار حتى تصبح الجلسة جاهزة أو حتى يحدث خطأ.

حدد قائمة بالجلسات النشطة

.\RenderingSession.ps1 -GetSessions

قم بإيقاف الجلسة

.\RenderingSession.ps1 -StopSession -Id <sessionID>

تغيير خصائص جلسة العمل

في الوقت الحالي، فإننا ندعم فقط تغيير maxLeaseTime للجلسة.

ملاحظة

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

.\RenderingSession.ps1 -UpdateSession -Id <sessionID> -MaxLeaseTime <hh:mm:ss>

البرنامج النصي: Conversion.ps1

يتم استخدام هذا البرنامج النصي لتحويل نماذج الإدخال إلى تنسيق وقت تشغيل محدد لخدمةAzure Remote Rendering GitHub.

هام

تأكد من ملء قسمي accountSettings و assetConversionSettings ، وخيار remoteRenderingDomain في renderingSessionSettings في arrconfig.json.

يوضح البرنامج النصي الخيارين لاستخدام حسابات التخزين مع الخدمة:

  • حساب تخزين مرتبط بحساب خدمة Azure Remote Rendering
  • توفير إمكانية الوصول إلى التخزين عبر توقيعات الوصول المشترك (SAS)

حساب تخزين مربوط

بمجرد تعبئة arrconfig.json بالكامل وربط حساب تخزين، يمكنك استخدام الأمر التالي. يتم وصف ربط حساب التخزين الخاص بك في قسم إنشاء حساب.

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

.\Conversion.ps1
  1. قم بتحميل جميع الملفات المضمنة assetConversionSettings.modelLocation في إلى حاوية كائن ثنائي كبير الحجم للإدخل ضمن المحدد inputFolderPath.
  2. استدعاء نموذج تحويل واجهة برمجة تطبيقات REST لبدء تحويل النموذج
  3. استطلاع حالة التحويل حتى نجاح التحويل أو فشله.
  4. تفاصيل الإخراج من موقع الملف المحول (حساب التخزين، حاوية الإخراج، مسار الملف في الحاوية).

الوصول إلى التخزين عبر توقيعات الوصول المشترك

.\Conversion.ps1 -UseContainerSas

وسيؤدي ذلك إلى:

  1. رفع الملف المحلي من assetConversionSettings.localAssetDirectoryPath حاوية blob الإدخال.
  2. إنشاء رابط URL لتوقيعات الوصول المشترك URI SAS من أجل حاوية الإدخال.
  3. إنشاء رابط URl لتوقيعات الوصول المشتركURI SAS من أجل حاوية الإخراج.
  4. استدعاء نموذج تحويل واجهة برمجة تطبيقات REST لبدء تحويل النموذج.
  5. استطلاع حالة التحويل حتى نجاح التحويل أو فشله.
  6. تفاصيل الإخراج من موقع الملف المحول (حساب التخزين، حاوية الإخراج، مسار الملف في الحاوية).
  7. إخراج عنوان URL لتوقيع الوصول المشترك URI من أجل النموذج المحول في حاوية blob الإخراج.

خيارات إضافية لسطر الأوامر

لاستخدام ملف تهيئة بديلة:

.\Conversion.ps1 -ConfigFile D:\arr\myotherconfigFile.json

لبدء جلسة عمل فقطبدون الاقتراع، يمكنك استخدام:

.\Conversion.ps1 -ConvertAsset

يمكنك تجاوز الإعدادات الفردية من ملف التهيئة باستخدام رموز تبديل سطر الأوامر التالية:

  • معرف الهوية: التحويل المستخدم مع حالة إتمام التحويل
  • هوية حساب طلب التطبيق: حساب طلب التطبيق من إعدادات الحسابات
  • مفتاح حساب طلب التطبيق: تخطي مفتاح حساب طلب التطبيق الخاص بإعدادات الحساب
  • ArrAccountDomain: تجاوز arrAccountDomain من accountSettings
  • RemoteRenderingDomain: تجاوز remoteRenderingDomain of renderingSessionSettings
  • مجموعة الموارد: تجاوز لمجموعة الموارد من إعدادات تحويل الأصول
  • اسم حساب التخزين: تجاوز اسم حساب التخزين الخاص بإعدادات تحويل الأصول
  • اسم حاوية إدخال Blob: تخطي اسم حاوية إدخال Blob من إعدادات تحويل الأصول
  • مسار مجلد الأصول المحلي: تجاوز مسار مجلد الأصول المحلي من إعدادات ضبط تحويل الأصول
  • مسار إدخال الأصول: تجاوز مسار إدخال الأصول الخاص بإعدادات تحويل الأصول
  • اسم حاوية إخراج Blob: تجاوز اسم حاوية إخراج Blob من إعدادات تحويل الأصول
  • مسار مجلد الإخراج: تجاوز مسار مجلد الإخراج من إعدادات تحويل الأصول
  • اسم ملف أصول الإخراج: تجاوز اسم ملف أصول الإخراج من إعدادات تحويل الأصول

على سبيل المثال، يمكنك دمج الخيارات المحددة مثل هذا:

.\Conversion.ps1 -LocalAssetDirectoryPath "C:\\models\\box" -InputAssetPath box.fbx -OutputFolderPath another/converted/box -OutputAssetFileName newConversionBox.arrAsset

تشغيل مراحل التحويل الفردية

إذا كنت تريد تشغيل الخطوات الفردية للعملية، يمكنك استخدام:

تحميل البيانات فقط من مسار مجلد أصول محلي معين.

.\Conversion.ps1 -Upload

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

.\Conversion.ps1 -ConvertAsset

ويمكنك استرداد حالة التحويل لهذا التحويل باستخدام:

.\Conversion.ps1 -GetConversionStatus -Id <conversionId> [-Poll]

يستخدم -Poll للانتظار حتى تصبح الجلسة جاهزة أو حتى يحدث خطأ.

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