Referensi definisi konektor data untuk Platform Koneksi or Tanpa Kode

Artikel
02/21/2024

Untuk membuat konektor data dengan Codeless Koneksi or Platform (CCP), gunakan dokumen ini sebagai tambahan untuk dokumen referensi Microsoft Sentinel REST API for Data Koneksi or Definitions. Khususnya dokumen referensi ini diperluas pada bagian berikut:

connectorUiConfig - menentukan elemen visual dan teks yang ditampilkan di halaman konektor data di Microsoft Azure Sentinel.

Untuk informasi selengkapnya, lihat Membuat konektor tanpa kode.

Definisi konektor data - Membuat atau memperbarui

Referensikan operasi Buat Atau Perbarui di dokumen REST API untuk menemukan versi API stabil atau pratinjau terbaru. Hanya operasi yang updateetag memerlukan nilai .

Metode PUT

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

Parameter URI

Untuk informasi selengkapnya tentang versi API terbaru, lihat Definisi Data Koneksi or - Membuat atau Memperbarui Parameter URI

Nama	Deskripsi
data Koneksi orDefinitionName	Definisi konektor data harus berupa nama yang unik dan sama dengan `name` parameter dalam isi permintaan.
resourceGroupName	Nama grup sumber daya, tidak peka huruf besar/kecil.
subscriptionId	ID langganan target.
workspaceName	Nama ruang kerja, bukan ID. Pola regex: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
versi api	Versi API yang digunakan untuk operasi ini.

Isi permintaan

Isi permintaan untuk membuat definisi konektor data CCP dengan API memiliki struktur berikut:

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

data Koneksi orDefinition memiliki properti berikut:

Nama	Wajib	Tipe	Deskripsi
Kind	Benar	String	`Customizable` untuk konektor data polling API atau `Static` sebaliknya
Properti.connectorUiConfig	Benar	JSON berlapis connectorUiConfig	Properti konfigurasi UI konektor data

Mengonfigurasi antarmuka pengguna konektor Anda

Bagian ini menjelaskan opsi konfigurasi yang tersedia untuk menyesuaikan antarmuka pengguna halaman konektor data.

Cuplikan layar berikut menunjukkan halaman konektor data sampel, disorot dengan angka yang sesuai dengan area penting antarmuka pengguna.

Screenshot of a sample data connector page with sections labeled 1 through 9.

Masing-masing elemen berikut dari bagian yang connectorUiConfig diperlukan untuk mengonfigurasi antarmuka pengguna sesuai dengan bagian Customizable Koneksi orUiConfig dari API.

Bidang	Wajib	Tipe	Deskripsi	Cuplikan layar area penting #
title	Benar	string	Judul ditampilkan di halaman konektor data	1
id		string	Mengatur ID konektor kustom untuk penggunaan internal
Logo		string	Jalur ke file gambar dalam format SVG. Jika tidak ada nilai yang dikonfigurasi, logo default akan digunakan.	2
penerbit	Benar	string	Penyedia konektor	3
descriptionMarkdown	Benar	string dalam markdown	Deskripsi untuk konektor dengan kemampuan untuk menambahkan bahasa markdown untuk meningkatkannya.	4
sampleQueries	Benar	JSON berlapis sampleQueries	Kueri bagi pelanggan untuk memahami cara menemukan data di log peristiwa.
graphQueries	Benar	JSON berlapis graphQueries	Kueri yang menyajikan penyerapan data selama dua minggu terakhir. Menyediakan salah satu kueri untuk seluruh jenis data milik konektor data, atau kueri yang berbeda untuk setiap jenis data.	5
graphQueriesTableName		Mengatur nama tabel tempat konektor menyisipkan data. Nama ini dapat digunakan dalam kueri lain dengan menentukan `{{graphQueriesTableName}}` tempat penampung di `graphQueries` dan `lastDataReceivedQuery` nilai.
dataTypes	Benar	JSON berlapis dataTypes	Daftar dari semua jenis data untuk konektor Anda, dan kueri untuk mengambil waktu dari peristiwa terakhir bagi setiap jenis data.	6
connectivityCriteria	Benar	JSON berlapis connectivityCriteria	Objek yang menentukan cara memverifikasi apakah konektor tersambung.	7
izin	Benar	JSON berlapis izin	Informasi yang ditampilkan di bawah bagian Prasyarat UI, yang mencantumkan izin yang diperlukan untuk mengaktifkan atau menonaktifkan konektor.	8
instructionSteps	Benar	JSON berlapis instruksi	Array bagian widget yang menjelaskan cara menginstal konektor, dan kontrol yang dapat ditindaklanjuti yang ditampilkan pada tab Instruksi .	9

connectivityCriteria

Bidang	Wajib	Tipe	Deskripsi
Jenis	Benar	String	Salah satu dari dua opsi berikut: `HasDataConnectors` - nilai ini adalah yang terbaik untuk konektor data polling API seperti CCP. Konektor dianggap terhubung dengan setidaknya satu koneksi aktif. `isConnectedQuery` – nilai ini paling baik untuk jenis konektor data lainnya. Konektor dianggap tersambung saat kueri yang disediakan mengembalikan data.
Value	Benar ketika jenis adalah `isConnectedQuery`	String	Kueri untuk menentukan apakah data diterima dalam periode waktu tertentu. Misalnya: `CommonSecurityLog \| where DeviceVendor == \"Vectra Networks\"\n\| where DeviceProduct == \"X Series\"\n \| summarize LastLogReceived = max(TimeGenerated)\n \| project IsConnected = LastLogReceived > ago(7d)"`

dataTypes

Nilai Array	Jenis	Deskripsi
nama	String	Deskripsi yang bermakna`lastDataReceivedQuery` untuk, termasuk dukungan untuk `graphQueriesTableName` variabel . Contoh: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	Kueri KQL yang mengembalikan satu baris, dan menunjukkan terakhir kali data diterima, atau tidak ada data jika tidak ada hasil. Contoh: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

Menentukan kueri yang menyajikan penyerapan data selama dua minggu terakhir.

Menyediakan salah satu kueri untuk seluruh jenis data milik konektor data, atau kueri yang berbeda untuk setiap jenis data.

Nilai Array	Jenis	Deskripsi
metricName	String	Nama yang bermakna untuk grafik Anda. Contoh: `Total data received`
legenda	String	String yang muncul pada legenda ke sebelah kanan bagan, termasuk referensi variabel. Contoh: `{{graphQueriesTableName}}`
baseQuery	String	Kueri yang memfilter peristiwa yang relevan, termasuk referensi variabel. Contoh: `TableName_CL \| where ProviderName == "myprovider"` atau `{{graphQueriesTableName}}`

permissions

Nilai array	Jenis	Deskripsi
kustom	String	Menjelaskan izin kustom apa pun yang diperlukan untuk koneksi data Anda, dalam sintaks berikut: `{` `"name":`string`,` `"description":`String `}` Contoh: Nilai kustom ditampilkan di bagian Prasyarat Microsoft Azure Sentinel dengan ikon informasi biru. Dalam contoh GitHub, nilai ini berkorelasi dengan baris Kunci token pribadi GITHub API: Anda memerlukan akses ke token pribadi GitHub...
lisensi	ENUM	Menentukan lisensi yang diperlukan, sebagai salah satu dari nilai berikut: `OfficeIRM`, `OfficeATP`, `Office365`, `AadP1P2`, `Mcas`, `Aatp`, `Mdatp`, `Mtp`, `IoT` Contoh: Nilai lisensi ditampilkan dalam Microsoft Sentinel sebagai: Lisensi: Diperlukan Azure AD Premium P2
resourceProvider	resourceProvider	Menjelaskan prasyarat untuk sumber daya Azure Anda. Contoh: Nilai resourceProvider ditampilkan di bagian Prasyarat Microsoft Azure Sentinel sebagai: Ruang kerja: diperlukan izin baca dan tulis. Kunci: izin baca untuk kunci bersama ke ruang kerja yang diperlukan.
penyewa	array nilai ENUM Contoh: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Menentukan izin yang diperlukan, sebagai satu atau lebih dari nilai-nilai berikut: `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Contoh: menampilkan nilai penyewa di Microsoft Azure Sentinel sebagai: Izin Penyewa: Memerlukan `Global Administrator` atau `Security Administrator` pada penyewa ruang kerja

resourceProvider

nilai sub array	Jenis	Deskripsi
penyedia	ENUM	Menjelaskan penyedia sumber daya, dengan salah satu nilai berikut: - `Microsoft.OperationalInsights/workspaces` - `Microsoft.OperationalInsights/solutions` - `Microsoft.OperationalInsights/workspaces/datasources` - `microsoft.aadiam/diagnosticSettings` - `Microsoft.OperationalInsights/workspaces/sharedKeys` - `Microsoft.Authorization/policyAssignments`
providerDisplayName	String	Item daftar di bawah Prasyarat yang menampilkan tanda centang merah "x" atau hijau saat requiredPermissions divalidasi di halaman konektor. Contoh `"Workspace"`
permissionsDisplayText	String	Menampilkan teks untuk izin Baca, Tulis, atau Baca dan Tulis yang harus sesuai dengan nilai yang dikonfigurasi dalam requiredPermissions
requiredPermissions	`{` `"action":`Boolean`,` `"delete":`Boolean`,` `"read":`Boolean`,` `"write":`Boolean `}`	Menjelaskan izin minimum yang diperlukan untuk konektor.
cakupan	ENUM	Menjelaskan cakupan konektor data, sebagai salah satu nilai berikut: `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

sampleQueries

nilai array	Jenis	Deskripsi
description	String	Deskripsi yang bermakna untuk kueri sampel. Contoh: `Top 10 vulnerabilities detected`
query	String	Kueri sampel digunakan untuk mengambil data tentang jenis data. Contoh: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

Mengonfigurasi opsi tautan lainnya

Untuk menentukan tautan sebaris menggunakan markdown, gunakan contoh berikut.

{
   "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)"
}

Untuk menentukan link sebagai templat ARM, gunakan contoh berikut sebagai panduan:

{
   "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

Bagian ini menyediakan parameter yang menentukan serangkaian instruksi yang muncul di halaman konektor data Anda di Microsoft Azure Sentinel dan memiliki struktur berikut:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]

Properti Array	Wajib	Tipe	Deskripsi
title		String	Menentukan judul untuk instruksi.
description		String	Menentukan deskripsi yang bermakna untuk instruksi Anda.
innerSteps		Array	Menentukan array dari langkah instruksi dalam.
instruksi	Benar	Array instruksi	Menentukan array instruksi dari jenis parameter tertentu.

petunjuk

Menampilkan sekelompok instruksi, dengan berbagai parameter dan kemampuan untuk menyarangkan lebih banyak instruksiSteps dalam grup. Parameter yang ditentukan di sini sesuai

Jenis	Properti array	Deskripsi
OAuthForm	OAuthForm	Koneksi dengan OAuth
Textbox	Textbox	Ini berpasangan dengan `ConnectionToggleButton`. Ada 4 jenis yang tersedia: `password` `text` `number` `email`
Koneksi ionToggleButton	Koneksi ionToggleButton	Picu penyebaran DCR berdasarkan informasi koneksi yang disediakan melalui parameter tempat penampung. Parameter berikut didukung oleh: `name` :Wajib `disabled` `isPrimary` `connectLabel` `disconnectLabel`
CopyableLabel	CopyableLabel	Memperlihatkan bidang teks dengan tombol salin di akhir. Saat tombol dipilih, nilai bidang disalin.
InfoMessage	InfoMessage	Menentukan pesan informasi sebaris.
InstructionStepsGroup	InstructionStepsGroup	Menampilkan sekelompok instruksi, secara opsional diperluas atau dapat diciutkan, di bagian instruksi terpisah.
InstallAgent	InstallAgent	Menampilkan tautan ke bagian lain Azure untuk mencapai berbagai persyaratan penginstalan.

OAuthForm

Komponen ini mengharuskan OAuth2 jenis tersebut ada di auth properti templat konektor data.

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

Kotak teks

Berikut adalah beberapa contoh jenisnya Textbox . Contoh-contoh ini sesuai dengan parameter yang digunakan di bagian contoh auth di Referensi konektor data untuk Platform Koneksi or Tanpa Kode. Untuk masing-masing dari 4 jenis, masing-masing memiliki label, placeholder, dan 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"
  }
}
]

Koneksi ionToggleButton

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

CopyableLabel

Contoh:

Screenshot of a copy value button in a field.

Kode sampel:

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}

Nilai Array	Wajib	Tipe	Deskripsi
fillWith		ENUM	Array dari variabel lingkungan digunakan untuk mengisi tempat penampung. Pisahkan beberapa tempat penampung dengan koma. Misalnya: `{0},{1}` Nilai yang didukung: `workspaceId`, `workspaceName`, `primaryKey`, `MicrosoftAwsAccount`, `subscriptionId`
Label	Benar	String	Tentukan teks untuk label di atas kotak teks.
value	Benar	String	Menentukan nilai yang akan ditampilkan dalam kotak teks, mendukung tempat penampung.
baris		Baris	Menentukan baris dalam area antarmuka pengguna. Secara default, set ke 1.
wideLabel		Boolean	Menentukan label lebar untuk string panjang. Secara default, set ke `false`.

InfoMessage

Berikut adalah contoh pesan informasi sebaris:

Screenshot of an inline information message.

Sebaliknya, gambar berikut menunjukkan pesan informasi yang tidak sebaris:

Screenshot of an information message that's not inline.

Nilai Array	Jenis	Deskripsi
text	String	Menentukan teks yang akan ditampilkan dalam pesan.
dapat dilihat	Boolean	Menentukan apakah pesan ditampilkan.
inline	Boolean	Menentukan cara pesan informasi ditampilkan. - `true`: (Direkomendasikan) Menampilkan pesan informasi yang disematkan dalam instruksi. - `false`: Menambahkan latar belakang biru.

InstructionStepsGroup

Berikut adalah contoh grup instruksi yang dapat diperluas:

Screenshot of an expandable, extra instruction group.

Nilai Array	Wajib	Tipe	Deskripsi
title	Benar	String	Menentukan judul untuk langkah instruksi.
description		String	Teks deskriptif opsional.
canCollapseAllSections		Boolean	Menentukan apabila bagian tersebut adalah akordeon yang dapat diciutkan atau tidak.
noFxPadding		Boolean	Jika `true`, mengurangi lapisan ketinggian untuk menghemat ruang.
diperluas		Boolean	Jika `true` menampilkan sebagai diperluas secara default.

Untuk contoh terperinci, lihat konfigurasi JSON untuk konektor DNS Windows.

InstallAgent

Beberapa jenis InstallAgent muncul sebagai tombol, yang lain muncul sebagai tautan. Berikut adalah contoh keduanya:

Screenshot of a link added as inline text.

Nilai Array	Wajib	Tipe	Deskripsi
linkType	Benar	ENUM	Menentukan jenis tautan, sebagai salah satu nilai berikut: `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	Benar saat menggunakan `OpenPolicyAssignment` linkType.	String	Untuk konektor berbasis kebijakan, menentukan GUID dari definisi kebijakan bawaan.
assignMode		ENUM	Untuk konektor berbasis kebijakan, mendefinisikan mode penetapan, sebagai salah satu nilai berikut: `Initiative`, `Policy`
dataCollectionRuleType		ENUM	Untuk konektor berbasis DCR, menentukan jenis jenis aturan pengumpulan data sebagai `SecurityEvent`, atau `ForwardEvent`.

Contoh definisi konektor data

Contoh berikut menyatukan beberapa komponen yang ditentukan dalam artikel ini sebagai format isi JSON untuk digunakan dengan API definisi konektor data Buat Atau Perbarui.

Untuk contoh lebih lanjut connectorUiConfig tentang tinjau konektor data CCP lainnya. Bahkan konektor yang menggunakan CCP warisan memiliki contoh pembuatan UI yang valid.

{
    "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"
                  }
                }
              ]
            }
          ]
        }
    }
}

Share via