مشاركة عبر

مرجع تعريفات موصل البيانات للنظام الأساسي للموصل بدون تعليمات برمجية

  • مقالة

لإنشاء موصل بيانات باستخدام النظام الأساسي للموصل بدون تعليمات برمجية (CCP)، استخدم هذا المستند كملحق ل Microsoft Sentinel REST API للمستندات المرجعية لتعريفات موصل البيانات. على وجه التحديد، يتوسع هذا المستند المرجعي في القسم التالي:

  • connectorUiConfig - يحدد العناصر المرئية والنص المعروض على صفحة موصل البيانات في Microsoft Sentinel.

لمزيد من المعلومات، راجع إنشاء موصل بدون تعليمات برمجية.

تعريفات موصل البيانات - إنشاء أو تحديث

راجع عملية الإنشاء أو التحديث في مستندات واجهة برمجة تطبيقات REST للعثور على أحدث إصدار ثابت أو إصدار معاينة لواجهة برمجة التطبيقات. update تتطلب etag العملية فقط القيمة .

أسلوب PUT

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/{{dataConnectorDefinitionName}}?api-version={{apiVersion}}

معلمات URI

لمزيد من المعلومات حول أحدث إصدار من واجهة برمجة التطبيقات، راجع تعريفات موصل البيانات - إنشاء معلمات URI أو تحديثها

Name ‏‏الوصف
dataConnectorDefinitionName يجب أن يكون تعريف موصل البيانات اسما فريدا وهو نفس المعلمة name في نص الطلب.
resourceGroupName اسم مجموعة الموارد، وليس حساسا لحالة الأحرف.
subscriptionId معرف الاشتراك الهدف.
اسم مساحة العمل اسم مساحة العمل، وليس المعرف.
نمط Regex: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
إصدار واجهة برمجة التطبيقات إصدار واجهة برمجة التطبيقات لاستخدامه لهذه العملية.

نص الطلب

يحتوي نص الطلب لإنشاء تعريف موصل بيانات CCP باستخدام واجهة برمجة التطبيقات على البنية التالية:

{
    "kind": "Customizable",
    "properties": {
        "connectorUIConfig": {}
    }
}

يحتوي dataConnectorDefinition على الخصائص التالية:

الاسم مطلوبة نوع الوصف
النوع صواب السلسلة‬ Customizable لموصل بيانات التحقق من واجهة برمجة التطبيقات أو Static غير ذلك
خصائص.ConnectorUiConfig صواب JSON المتداخل
ConnectorUiConfig		 خصائص تكوين واجهة المستخدم لموصل البيانات

تكوين واجهة مستخدم الموصل

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

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

لقطة شاشة لصفحة موصل بيانات نموذجية مع أقسام تسمى من 1 إلى 9.

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

الحقل المطلوب نوع ‏‏الوصف لقطة شاشة لمنطقة بارزة #
title صواب سلسلة العنوان المعروض في صفحة موصل البيانات 1
معرف سلسلة تعيين معرف موصل مخصص للاستخدام الداخلي
شعار سلسلة المسار إلى ملف الصورة بتنسيق SVG. إذا لم يتم تكوين أي قيمة، يتم استخدام شعار افتراضي. 2
publisher صواب سلسلة موفر الموصل 3
descriptionMarkdown صواب سلسلة في markdown وصف للموصل مع القدرة على إضافة لغة markdown لتحسينه. 4
sampleQueries صواب JSON المتداخل
sampleQueries		 استعلامات للعميل لفهم كيفية العثور على البيانات في سجل الأحداث.
graphQueries صواب JSON المتداخل
graphQueries		 الاستعلامات التي تقدم استيعاب البيانات على مدار الأسبوعين الماضيين.

وفّر إما استعلام واحد لجميع أنواع بيانات موصل البيانات، أو استعلامات مختلفة لكل نوع بيانات.		 5
graphQueriesTableName تعيين اسم الجدول الذي يدرج الموصل البيانات إليه. يمكن استخدام هذا الاسم في استعلامات أخرى عن طريق تحديد {{graphQueriesTableName}} العنصر النائب في graphQueries lastDataReceivedQuery والقيم.
dataTypes صواب JSON المتداخل
dataTypes		 قائمة بجميع أنواع البيانات للموصل، واستعلام لإحضار وقت الحدث الأخير لكل نوع بيانات. 6
connectivityCriteria صواب JSON المتداخل
connectivityCriteria		 كائن يحدد كيفية التحقق مما إذا كان الموصل متصلا. 7
اذونات صواب JSON المتداخل
اذونات		 المعلومات المعروضة ضمن قسم المتطلبات الأساسية في واجهة المستخدم، والتي تسرد الأذونات المطلوبة لتمكين الموصل أو تعطيله. 8
instructionSteps صواب JSON المتداخل
التوجيهات		 صفيف من أجزاء عنصر واجهة المستخدم التي تشرح كيفية تثبيت الموصل، وعناصر التحكم القابلة للتنفيذ المعروضة في علامة التبويب إرشادات . 9

connectivityCriteria

الحقل المطلوب نوع ‏‏الوصف
النوع صواب السلسلة‬ أحد الخيارين التاليين: HasDataConnectors - هذه القيمة هي الأفضل لموصلات بيانات التحقق من واجهة برمجة التطبيقات مثل CCP. يعتبر الموصل متصلا باتصال نشط واحد على الأقل.

isConnectedQuery – هذه القيمة هي الأفضل للأنوع الأخرى من موصلات البيانات. يعتبر الموصل متصلا عندما يقوم الاستعلام المقدم بإرجاع البيانات.
القيمة‬ صواب عندما يكون النوع isConnectedQuery السلسلة‬ استعلام لتحديد ما إذا تم تلقي البيانات في غضون فترة زمنية معينة. على سبيل المثال: CommonSecurityLog | where DeviceVendor == \"Vectra Networks\"\n| where DeviceProduct == \"X Series\"\n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(7d)"

dataTypes

قيمة الصفيف النوع ‏‏الوصف
الاسم السلسلة‬ وصف ذي معنى ل، بما فيlastDataReceivedQuerygraphQueriesTableName ذلك دعم المتغير.

مثال: {{graphQueriesTableName}}
lastDataReceivedQuery السلسلة‬ استعلام KQL الذي يقوم بإرجاع صف واحد، ويشير إلى آخر مرة تم فيها تلقي البيانات، أو عدم وجود بيانات إذا لم تكن هناك نتائج.

مثال: {{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

graphQueries

تعريف استعلام يعرض استيعاب البيانات على مدار الأسبوعين الماضيين.

وفّر إما استعلام واحد لجميع أنواع بيانات موصل البيانات، أو استعلامات مختلفة لكل نوع بيانات.

قيمة الصفيف النوع ‏‏الوصف
اسم القياس السلسلة‬ اسم معبر للرسم البياني.

مثال: Total data received
legend السلسلة‬ السلسلة التي تظهر في وسيلة الإيضاح إلى يمين المخطط، بما في ذلك مرجع متغير.

مثال: {{graphQueriesTableName}}
baseQuery السلسلة‬ الاستعلام الذي يقوم بتصفية الأحداث ذات الصلة، بما في ذلك مرجع متغير.

على سبيل المثال: TableName_CL | where ProviderName == "myprovider" أو {{graphQueriesTableName}}

permissions

قيمة الصفيف النوع ‏‏الوصف
customs السلسلة‬ يصف أي أذونات مخصصة مطلوبة لاتصال البيانات، في بناء الجملة التالي:
{
"name":string,
"description":خيط
}

مثال: يتم عرض قيمة الجمارك في قسم المتطلبات الأساسية ل Microsoft Sentinel مع أيقونة إعلامية زرقاء. في مثال GitHub، ترتبط هذه القيمة بخط مفتاح الرمز المميز الشخصي لواجهة برمجة تطبيقات GitHub: تحتاج إلى الوصول إلى الرمز المميز الشخصي GitHub...
licenses قائمة تعداد تحديد التراخيص المطلوبة كأحد القيم التالية: OfficeIRM,OfficeATP, Office365, AadP1P2, Mcas, Aatp, Mdatp, Mtp, IoT

مثال: تظهر قيمة التراخيص في Microsoft Sentinel كما يلي: الترخيص: يجب توفر Azure AD Premium P2
resourceProvider resourceProvider وصف أي متطلبات أساسية لمورد Azure.

مثال: تعرض قيمة resourceProvider في قسم المتطلبات الأساسية ل Microsoft Sentinel على النحو التالي:
مساحة العمل: مطلوب إذن القراءة والكتابة.
المفاتيح: يجب توفر أذونات القراءة للمفاتيح المشتركة لمساحة العمل.
tenant صفيف قيم ENUM
مثال:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 تحديد الأذونات المطلوبة، كقيمة واحدة أو أكثر من القيم التالية: "GlobalAdmin", "SecurityAdmin", "SecurityReader", "InformationProtection"

مثال: يعرض قيمة المستأجر في Microsoft Sentinel على النحو التالي: أذونات المستأجر: يتطلب Global Administrator أو Security Administrator على مستأجر مساحة العمل

هام

توصي Microsoft باستخدام الأدوار بأقل عدد من الأذونات. يساعد هذا في تحسين الأمان لمؤسستك. المسؤول العام هو دور متميز للغاية يجب أن يقتصر على سيناريوهات الطوارئ عندما لا يمكنك استخدام دور موجود.

resourceProvider

قيمة الصفيف الفرعي النوع ‏‏الوصف
provider قائمة تعداد يصف موفر الموارد، بإحدى القيم التالية:
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName السلسلة‬ عنصر قائمة ضمن المتطلبات الأساسية يعرض علامة اختيار حمراء "x" أو خضراء عند التحقق من صحة الأذونات المطلوبة في صفحة الموصل. مثل "Workspace"
permissionsDisplayText السلسلة‬ عرض نص لأذونات القراءة أو الكتابة أو القراءة والكتابة التي يجب أن تتوافق مع القيم المكونة في الأذونات المطلوبة
requiredPermissions {
"action":منطقيه,
"delete":منطقيه,
"read":منطقيه,
"write":منطقيه
}		 توضح هذه المقالة الحد الأدنى من الأذونات المطلوبة للموصل.
النطاق قائمة تعداد وصف نطاق موصل البيانات، كأحد القيم التالية: "Subscription", "ResourceGroup", "Workspace"

sampleQueries

قيمة الصفيف النوع ‏‏الوصف
الوصف السلسلة‬ وصف معبر لعينة الاستعلام.

مثال: Top 10 vulnerabilities detected
الاستعلام السلسلة‬ عينة استعلام تُستخدم لإحضار بيانات نوع البيانات.

مثال: {{graphQueriesTableName}}\n | sort by TimeGenerated\n | take 10

لتعريف ارتباط مضمن باستخدام markdown، استخدم المثال التالي.

{
   "title": "",
   "description": "Make sure to configure the machine's security according to your organization's security policy\n\n\n[Learn more >](https://aka.ms/SecureCEF)"
}

لتعريف ارتباط كقالب ARM، استخدم المثال التالي كإرشاد:

{
   "title": "Azure Resource Manager (ARM) template",
   "description": "1. Click the **Deploy to Azure** button below.\n\n\t[![Deploy To Azure](https://aka.ms/deploytoazurebutton)]({URL to custom ARM template})"
}

instructionSteps

يوفر هذا القسم معلمات تحدد مجموعة الإرشادات التي تظهر على صفحة موصل البيانات في Microsoft Sentinel وتحتوي على البنية التالية:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
خاصية الصفيف المطلوب نوع ‏‏الوصف
title السلسلة‬ يحدد عنوانًا للتعليمات.
الوصف السلسلة‬ يحدد وصفًا معبرًا للتعليمات.
innerSteps صفيف يحدد صفيفًا من خطوات التعليمات الداخلية.
التوجيهات صواب صفيف التعليمات تعريف صفيف من الإرشادات لنوع معلمة معين.

التوجيهات

يعرض مجموعة من الإرشادات، مع معلمات مختلفة والقدرة على تداخل المزيد من التعليماتالتضمينات في المجموعات. تتوافق المعلمات المحددة هنا

نوع خاصية الصفيف ‏‏الوصف
OAuthForm OAuthForm الاتصال ب OAuth
مربع النص مربع النص هذا يقترن ب ConnectionToggleButton. هناك 4 أنواع متوفرة:
  • password
  • text
  • number
  • email
    		•
    ConnectionToggleButton ConnectionToggleButton تشغيل نشر DCR استنادا إلى معلومات الاتصال المتوفرة من خلال معلمات العنصر النائب. المعلمات التالية مدعومة:
  • name :إجباري
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    CopyableLabel CopyableLabel إظهار حقل نصي مع زر نسخ في النهاية. عند تحديد الزر، يتم نسخ قيمة الحقل.
    InfoMessage InfoMessage يحدد رسالة معلومات مُضمنة.
    مجموعة الخطوات الإرشادية مجموعة الخطوات الإرشادية يعرض مجموعة من الإرشادات، موسعة اختياريا أو قابلة للطي، في قسم إرشادات منفصل.
    InstallAgent InstallAgent يعرض ارتباطا إلى أجزاء أخرى من Azure لإنجاز متطلبات التثبيت المختلفة.

    OAuthForm

    يتطلب هذا المكون وجود OAuth2 النوع في auth خاصية قالب موصل البيانات.

    "instructions": [
{
  "type": "OAuthForm",
  "parameters": {
    "clientIdLabel": "Client ID",
    "clientSecretLabel": "Client Secret",
    "connectButtonLabel": "Connect",
    "disconnectButtonLabel": "Disconnect"
  }          
}
]

    Textbox

    فيما يلي بعض الأمثلة على Textbox النوع. تتوافق هذه الأمثلة مع المعلمات المستخدمة في قسم المثال auth في مرجع موصلات البيانات للنظام الأساسي للموصل بدون تعليمات برمجية. لكل نوع من الأنواع ال 4، يحتوي labelكل منها على و placeholderو name.

    "instructions": [
{
  "type": "Textbox",
  "parameters": {
      {
        "label": "User name",
        "placeholder": "User name",
        "type": "text",
        "name": "username"
      }
  }
},
{
  "type": "Textbox",
  "parameters": {
      "label": "Secret",
      "placeholder": "Secret",
      "type": "password",
      "name": "password"
  }
}
]

    ConnectionToggleButton

    "instructions": [
{
  "type": "ConnectionToggleButton",
  "parameters": {
    "connectLabel": "toggle",
    "name": "toggle"
  }          
}
]

    CopyableLabel

    مثال:

    لقطة شاشة لزر قيمة النسخ في أحد الحقول.

    عينة التعليمات البرمجية:

    {
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
    قيمة الصفيف المطلوب نوع ‏‏الوصف
    fillWith قائمة تعداد صفيف متغيرات البيئة المُستخدم لملء عنصر نائب. يفصل العناصر النائبة المتعددة بفواصل. على سبيل المثال: {0},{1}

    القيم المدعومة: workspaceId, workspaceName, primaryKey, MicrosoftAwsAccount, subscriptionId
    تسميه صواب السلسلة‬ تعريف نص التسمية أعلى مربع نص.
    قيمة صواب السلسلة‬ تحديد القيمة التي ستُعرض في مربع النص، ويدعم العناصر النائبة.
    الصفوف صفوف يحدد الصفوف في منطقة واجهة المستخدم. يُعيّن إلى 1 بشكل افتراضي.
    wideLabel Boolean تحديد تسمية واسعة للسلاسل الطويلة. يُعيّن إلى false بشكل افتراضي.

    InfoMessage

    فيما يلي مثال على رسالة معلومات مضمنة:

    لقطة شاشة لرسالة معلومات مُضمنة.

    في المقابل، تعرض الصورة التالية رسالة معلومات غير مضمنة:

    لقطة شاشة لرسالة معلومات غير مضمنة.

    قيمة الصفيف النوع الوصف
    text السلسلة‬ يحدد النص المراد عرضه في الرسالة.
    visible Boolean تحديد ما إذا كانت الرسالة معروضة أم لا.
    inline Boolean تحديد كيفية عرض رسالة المعلومات.

    - true: (مستحسن) يعرض رسالة المعلومات المُضمنة في الإرشادات.
    - false: يضيف خلفية زرقاء.

    مجموعة الخطوات الإرشادية

    فيما يلي مثال على مجموعة تعليمات قابلة للتوسيع:

    لقطة شاشة لمجموعة تعليمات إضافية قابلة للتوسيع.

    قيمة الصفيف المطلوب نوع ‏‏الوصف
    title صواب السلسلة‬ تحديد عنوان خطوة التعليمات.
    الوصف السلسلة‬ نص وصفي اختياري.
    canCollapseAllSections Boolean يحدد ما إذا كان القسم عبارة عن أكورديون قابل للطي أم لا.
    noFxPadding Boolean إذا كان true، فإنه يقلل من مساحة الارتفاع المتروكة لتوفير مساحة.
    expanded Boolean إذا كان true، فإنه يظهر على أنه مُوسع بشكل افتراضي.

    للحصول على مثال مفصل، راجع تكوين JSON لموصل Windows DNS.

    InstallAgent

    تظهر بعض أنواع InstallAgent كزر، بينما يظهر البعض الآخر كارتباط. فيما يلي أمثلة على كليهما:

    لقطة شاشة لارتباط مُضاف كزر.

    لقطة شاشة لارتباط مُضاف كنص مضمّن.

    قيم الصفيف المطلوب نوع ‏‏الوصف
    linkType صواب قائمة تعداد تحديد نوع الارتباط، كأحد القيم التالية:

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid صواب عند استخدام OpenPolicyAssignment linkType. السلسلة‬ بالنسبة للموصلات المستندة إلى النهج، يحدد GUID لتعريف النهج المُضمن.
    assignMode قائمة تعداد بالنسبة للموصلات المستندة إلى النهج، يحدد وضع التعيين، كأحد القيم التالية: Initiative, Policy
    dataCollectionRuleType قائمة تعداد بالنسبة للموصلات المستندة إلى DCR، يعرف نوع قاعدة جمع البيانات إما SecurityEventأو .ForwardEvent

    مثال تعريف موصل البيانات

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

    لمزيد من الأمثلة على connectorUiConfig مراجعة موصلات بيانات CCP الأخرى. حتى الموصلات التي تستخدم CCP القديمة لها أمثلة صالحة لإنشاء واجهة المستخدم.

    {
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
          "title": "Example CCP Data Connector",
          "publisher": "My Company",
          "descriptionMarkdown": "This is an example of data connector",
          "graphQueriesTableName": "ExampleConnectorAlerts_CL",
          "graphQueries": [
            {
              "metricName": "Alerts received",
              "legend": "My data connector alerts",
              "baseQuery": "{{graphQueriesTableName}}"
            },   
           {
              "metricName": "Events received",
              "legend": "My data connector events",
              "baseQuery": "ASIMFileEventLogs"
            }
          ],
            "sampleQueries": [
            {
                "description": "All alert logs",
                "query": "{{graphQueriesTableName}} \n | take 10"
            }
          ],
          "dataTypes": [
            {
              "name": "{{graphQueriesTableName}}",
              "lastDataReceivedQuery": "{{graphQueriesTableName}} \n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)"
            },
             {
              "name": "ASIMFileEventLogs",
              "lastDataReceivedQuery": "ASIMFileEventLogs \n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)"
             }
          ],
          "connectivityCriteria": [
            {
              "type": "HasDataConnectors"
            }
          ],
          "permissions": {
            "resourceProvider": [
              {
                "provider": "Microsoft.OperationalInsights/workspaces",
                "permissionsDisplayText": "Read and Write permissions are required.",
                "providerDisplayName": "Workspace",
                "scope": "Workspace",
                "requiredPermissions": {
                  "write": true,
                  "read": true,
                  "delete": true
                }
              },
            ],
            "customs": [
              {
                "name": "Example Connector API Key",
                "description": "The connector API key username and password is required"
              }
            ] 
        },
          "instructionSteps": [
            {
              "title": "Connect My Connector to Microsoft Sentinel",
              "description": "To enable the connector provide the required information below and click on Connect.\n>",
              "instructions": [
               {
                  "type": "Textbox",
                  "parameters": {
                    "label": "User name",
                    "placeholder": "User name",
                    "type": "text",
                    "name": "username"
                  }
                },
                {
                  "type": "Textbox",
                  "parameters": {
                    "label": "Secret",
                    "placeholder": "Secret",
                    "type": "password",
                    "name": "password"
                  }
                },
                {
                  "type": "ConnectionToggleButton",
                  "parameters": {
                    "connectLabel": "toggle",
                    "name": "toggle"
                  }
                }
              ]
            }
          ]
        }
    }
}