المصادقة والتخويل ل Azure Time Series Insights API

  • مقالة
  • قراءة خلال 9 دقائق

ملاحظة

لن يتم دعم خدمة Insights السلاسل الزمنية (TSI) بعد مارس 2025. فكر في ترحيل بيئات TSI الحالية إلى حلول بديلة في أقرب وقت ممكن. لمزيد من المعلومات حول الإهمال والترحيل، يرجى زيارة وثائقنا.

بناء على احتياجات عملك، قد يتضمن الحل الخاص بك تطبيقا واحدا أو أكثر من تطبيقات العميل التي تستخدمها للتفاعل مع واجهات برمجة التطبيقات الخاصة ببيئة Azure Time Series Insights. يقوم Azure Time Series Insights بإجراء المصادقة باستخدام رموز أمان Azure AD استنادا إلى OAUTH 2.0. لمصادقة عميلك (عملائك) ، ستحتاج إلى الحصول على رمز مميز لحامله مع الأذونات الصحيحة ، وتمريره مع مكالمات واجهة برمجة التطبيقات. يصف هذا المستند عدة طرق للحصول على بيانات الاعتماد التي يمكنك استخدامها للحصول على رمز مميز لحامله والمصادقة، بما في ذلك استخدام الهوية المدارة وتسجيل تطبيق Azure Active Directory.

الهويات المُدارة

توضح الأقسام التالية كيفية استخدام هوية مدارة من Azure Active Directory (Azure AD) للوصول إلى Azure Time Series Insights API. على Azure، تلغي الهويات المدارة حاجة المطورين إلى إدارة بيانات الاعتماد من خلال توفير هوية لمورد Azure في Azure AD واستخدامه للحصول على الرموز المميزة ل Azure Active Directory (Azure AD). فيما يلي بعض فوائد استخدام الهويات المُدارة:

  • لست بحاجة إلى إدارة بيانات الاعتماد. بيانات الاعتماد غير متاحة لك.
  • يمكنك استخدام الهويات المدارة للمصادقة على أي خدمة Azure تدعم مصادقة Azure AD بما في ذلك Azure Key Vault.
  • يمكن استخدام الهويات المدارة بدون أي تكلفة إضافية.

لمزيد من المعلومات حول نوعي الهويات المدارة ، راجع ما هي الهويات المدارة لموارد Azure؟

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

  • الأجهزة الظاهرية لـ Azure
  • خدمة تطبيق Azure
  • دالات Azure
  • Azure Container instances
  • وأكثر من ذلك ...

راجع خدمات Azure التي تدعم الهويات المدارة لموارد Azure للحصول على القائمة الكاملة.

تسجيل تطبيق Azure Active Directory

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

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

في حالة تسجيل تطبيق في المدخل، يتم إنشاء تلقائيًا عنصر التطبيق وكذلك عنصر كيان الخدمة في المستأجر المنزل. في حالة تسجيل/إنشاء تطبيق باستخدام واجهات برمجة التطبيقات Microsoft Graph، فإن إنشاء عنصر كيان الخدمة يُعد خطوة منفصلة. مطلوب كائن أساسي للخدمة لطلب الرموز المميزة.

تأكد من مراجعة قائمة التحقق من الأمان للتطبيق الخاص بك. كأفضل ممارسة ، يجب عليك استخدام بيانات اعتماد الشهادة ، وليس بيانات اعتماد كلمة المرور (أسرار العميل).

راجع الكائنات الأساسية للتطبيق والخدمة في Azure Active Directory لمزيد من التفاصيل.

الخطوة 1: إنشاء هويتك المدارة أو تسجيل التطبيق

بمجرد تحديد ما إذا كنت ستستخدم هوية مدارة أو تسجيلا للتطبيق، فإن خطوتك التالية هي توفير واحدة.

الهوية المُدارة

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

تسجيل التطبيق

اتبع الخطوات المذكورة في تسجيل طلب.

  • بعد تحديد النظام الأساسي المناسب في الخطوة 4 من تكوين إعدادات النظام الأساسي ، قم بتكوين عناوين URI لإعادة التوجيهورموز الوصول في اللوحة الجانبية على يمين واجهة المستخدم.

    • يجب أن تتطابق عناوين URI لإعادة التوجيه مع العنوان الذي يوفره طلب المصادقة:

      • بالنسبة للتطبيقات المستضافة في بيئة تطوير محلية، حدد عميل عام (سطح مكتب محمول & ). تأكد من تعيين العميل العام إلى نعم.
      • بالنسبة Single-Page التطبيقات المستضافة على خدمة تطبيقات Azure، حدد ويب.

    • حدد ما إذا كان عنوان URL لتسجيل الخروج مناسبا أم لا.

    • قم بتمكين تدفق المنحة الضمني عن طريق التحقق من رموز Access أو رموزالمعرف.

    Create Redirect URIs

    انقر على تكوين، ثم حفظ.

  • قم بإقران تطبيق Azure Active Directory الخاص بك Azure Time Series Insights. حدد أذونات واجهة برمجة التطبيقاتإضافة>أذوناتواجهات>برمجة التطبيقات التي تستخدمها مؤسستي.

    Associate an API with your Azure Active Directory app

    اكتب Azure Time Series Insights في شريط البحث ثم حدد Azure Time Series Insights.

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

    Specify the kind of API permission your app requires

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

الخطوة 2: منح حق الوصول

عندما تتلقى بيئة Insights Azure Time Series طلبا ما، يتم أولا التحقق من صحة الرمز المميز لحامل المتصل. إذا تم التحقق من الصحة ، فقد تمت مصادقة المتصل ، ثم يتم إجراء فحص آخر لضمان تفويض المتصل بتنفيذ الإجراء المطلوب. لتفويض أي مستخدم أو مدير خدمة، يجب عليك أولا منحهم حق الوصول إلى البيئة عن طريق تعيينهم إما دور القارئ أو المساهم.

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

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

    az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"

ملاحظة

يتطلب ملحق timeseriesinsights ل Azure CLI الإصدار 2.11.0 أو أعلى. سيتم تثبيت الإضافة تلقائيا في المرة الأولى التي تقوم فيها بتشغيل أمر سياسة الوصول az tsi. تعرف على المزيد حول الملاحق.

الخطوة 3: طلب الرموز المميزة

بمجرد توفير هويتك المدارة أو تسجيل التطبيق وتعيين دور، تصبح جاهزا لبدء استخدامه لطلب الرموز المميزة لحامل OAuth 2.0. ستختلف الطريقة التي تستخدمها للحصول على رمز مميز اعتمادا على مكان استضافة التعليمات البرمجية واللغة التي تختارها. عند تحديد المورد (المعروف أيضا باسم "جمهور" الرمز المميز)، يمكنك تحديد Insights Azure Time Series من خلال عنوان URL أو المعرف الفريد العمومي الخاص به:

  • https://api.timeseries.azure.com/
  • 120d688d-1518-4cf7-bd38-182f158850b6

هام

إذا كنت تستخدم عنوان URL كمعرف المورد، فيجب إصدار الرمز المميز بالضبط إلى https://api.timeseries.azure.com/. الشرطة المائلة الزائدة مطلوبة.

  • إذا كنت تستخدم ساعي البريد ، فسيكون AuthURL الخاص بك: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ صالح ولكنه https://api.timeseries.azure.com ليس كذلك.

الهويات المُدارة

عند الوصول من خدمة Azure App أو وظائفها، اتبع الإرشادات الواردة في الحصول على الرموز المميزة لموارد Azure.

بالنسبة لتطبيقات ودالات .NET، فإن أبسط طريقة للعمل مع هوية مدارة هي من خلال مكتبة عميل Azure Identity ل .NET. تحظى مكتبة العملاء هذه بشعبية بسبب بساطتها وفوائدها الأمنية. يمكن للمطورين كتابة التعليمات البرمجية مرة واحدة والسماح لمكتبة العميل بتحديد كيفية المصادقة استنادا إلى بيئة التطبيق - سواء على محطة عمل مطور باستخدام حساب مطور أو تم نشرها في Azure باستخدام هوية خدمة مدارة. للحصول على إرشادات الترحيل من مكتبة AppAuthentication السابقة ، اقرأ AppAuthentication إلى Azure.Identity Migration Guide.

طلب رمز مميز ل Azure Time Series Insights باستخدام C# ومكتبة عميل Azure Identity ل .NET:

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

تسجيل تطبيق

  • يمكن للمطورين استخدام مكتبة مصادقة Microsoft (MSAL) للحصول على الرموز المميزة لتسجيلات التطبيقات.

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

للحصول على نموذج التعليمات البرمجية C # الذي يوضح كيفية الحصول على رمز مميز كبيانات تسجيل تطبيق والاستعلام من بيئة Gen2، اعرض نموذج التطبيق على GitHub

هام

إذا كنت تستخدم مكتبة مصادقة Azure Active Directory (ADAL) اقرأ حول الترحيل إلى MSAL.

الرؤوس والمعلمات الشائعة

يصف هذا القسم رؤوس طلبات HTTP الشائعة والمعلمات المستخدمة لإجراء استعلامات مقابل Insights واجهات برمجة تطبيقات Gen1 وGen2 من Azure Series وGen2. تتم تغطية المتطلبات الخاصة بواجهة برمجة التطبيقات بمزيد من التفصيل في الوثائق المرجعية لواجهة برمجة تطبيقات Azure Time Series Insights REST.

تلميح

اقرأ مرجع واجهة برمجة تطبيقات Azure REST لمعرفة المزيد حول كيفية استهلاك واجهات برمجة تطبيقات REST وإجراء طلبات HTTP ومعالجة استجابات HTTP.

عناوين HTTP

يتم وصف رؤوس الطلبات المطلوبة أدناه.

رأس الطلب المطلوب الوصف
التخويل للمصادقة باستخدام Azure Time Series Insights، يجب تمرير رمز مميز صالح لحامل OAuth 2.0 في رأس التفويض.

تلميح

اقرأ تصور عينة Azure Time Series Insights العميل المستضاف لمعرفة كيفية المصادقة باستخدام Azure Time Series Insights واجهات برمجة التطبيقات برمجيا باستخدام حزمة SDK لعميل JavaScript إلى جانب المخططات والرسوم البيانية.

يتم وصف رؤوس الطلبات الاختيارية أدناه.

رأس طلب اختياري الوصف
نوع المحتوى application/json فقط مدعوم.
x-ms-client-request-id معرف طلب العميل. تسجل الخدمة هذه القيمة. يسمح للخدمة بتتبع التشغيل عبر الخدمات.
x-ms-client-session-id معرف جلسة عمل العميل. تسجل الخدمة هذه القيمة. يسمح للخدمة بتتبع مجموعة من العمليات ذات الصلة عبر الخدمات.
x-ms-client-application-name اسم التطبيق الذي أنشأ هذا الطلب. تسجل الخدمة هذه القيمة.

فيما يلي وصف لرؤوس الاستجابة الاختيارية ولكن الموصى بها.

رأس الاستجابة الوصف
نوع المحتوى يتم دعم application/json فقط.
x-ms-request-id معرف الطلب الذي تم إنشاؤه بواسطة الخادم. يمكن استخدامه للاتصال ب Microsoft للتحقيق في طلب.
x-ms-property-not-found-behavior رأس استجابة اختياري لواجهة برمجة تطبيقات GA. القيم المحتملة هي ⁧ThrowError⁩ (افتراضي) أو ⁧UseNull⁩.

معلمات HTTP

تلميح

يمكنك العثور على مزيد من المعلومات حول معلومات الاستعلام المطلوبة والاختيارية في الوثائق المرجعية.

تعتمد معلمات سلسلة استعلام عنوان URL المطلوبة على إصدار واجهة برمجة التطبيقات.

الإصدار قيم إصدار واجهة برمجة التطبيقات
جين1 api-version=2016-12-12
Gen2 api-version=2020-07-31

تتضمن معلمات سلسلة استعلام عنوان URL الاختيارية تعيين مهلة لأوقات تنفيذ طلب HTTP.

معلمة الاستعلام الاختيارية الوصف إصدار
timeout=<timeout> مهلة من جانب الخادم لتنفيذ طلب HTTP. ينطبق فقط على واجهات برمجة تطبيقات "الحصول على أحداث البيئة" و "الحصول على تجميعات البيئة". يجب أن تكون قيمة المهلة بتنسيق مدة ISO 8601 ، على سبيل المثال "PT20S" ويجب أن تكون في النطاق 1-30 s. القيمة الافتراضية هي ⁧30 s⁩. جين1
storeType=<storeType> بالنسبة لبيئات Gen2 مع تمكين التخزين الدافئ ، يمكن تنفيذ الاستعلام إما على WarmStore أو ColdStore. تحدد هذه المعلمة في الاستعلام المخزن الذي يجب تنفيذ الاستعلام عليه. إذا لم يتم تعريفه ، تنفيذ الاستعلام على مخزن التبريد. للاستعلام عن المتجر الدافئ ، يجب تعيين storeType إلى WarmStore. إذا لم يتم تعريفه ، تنفيذ الاستعلام مقابل مخزن التبريد. Gen2

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