建立 Azure Data Explorer 的事件方格數據連線

發行項
03/08/2024

在本文中，您將瞭解如何使用事件方格數據連線，將 Blob 從記憶體帳戶內嵌至 Azure Data Explorer。您將建立設定 Azure 事件方格訂用帳戶的事件方格資料連線。事件方格訂用帳戶會透過 Azure 事件中樞，將事件從記憶體帳戶路由傳送至 Azure Data Explorer。

注意

擷取最多可支援 6GB 的檔案大小。建議內嵌 100 MB 和 1 GB 之間的檔案。

若要瞭解如何使用 Kusto SDK 建立連線，請參閱使用 SDK 建立事件方格數據連線。

如需從事件方格擷取至 Azure Data Explorer 的一般資訊，請參閱連線到事件方格。

注意

若要使用 Event Grid 連線達到最佳效能，請透過 Blob 元數據設定 rawSizeBytes 擷取屬性。如需詳細資訊，請參閱擷取屬性。

必要條件

Azure 訂用帳戶。建立 Azure 免費帳戶。
Azure 資料總管叢集和資料庫。建立叢集和資料庫。
目的地數據表。建立數據表或使用現有的數據表。
數據表的擷取對應。
記憶體帳戶。事件方格通知訂用BlobStorage帳戶可以在、 StorageV2或 Data Lake Storage Gen2 的 Azure 記憶體帳戶上設定。
註冊事件方格資源提供者。

建立事件方格資料連線

在本節中，您會建立 Event Grid 與 Azure Data Explorer 數據表之間的連線。

流覽至 Azure 入口網站中的 Azure Data Explorer 叢集。
在 [數據] 底下，選取 [ 資料庫>TestDatabase]。
在 [設定] 底下，選取 [數據連線]，然後選取 [新增數據>連線事件方格] (Blob 記憶體) 。

使用下列資訊填寫事件方格資料連線表單：

設定	建議的值	欄位描述
資料連線名稱	test-grid-connection	您想要在 Azure 資料總管中建立的連線名稱。數據連線名稱只能包含英數位元、虛線和點字元，長度最多為 40 個字元。
儲存體帳戶訂用帳戶	您的訂用帳戶識別碼	儲存體帳戶所在的訂用帳戶識別碼。
事件類型	blob 已建立或 blob 已重新命名	觸發擷取的事件類別。只有 ADLSv2 儲存體支援 blob 已重新命名。若要重新命名 Blob，請流覽至 Azure 入口網站中的 Blob，以滑鼠右鍵按兩下 Blob，然後選取 [重新命名]。支援的型別：Microsoft.Storage.BlobCreated 或 Microsoft.Storage.BlobRenamed。
儲存體帳戶	gridteststorage1	您先前建立之儲存體帳戶的名稱。
資源建立	自動	開啟自動資源建立表示 Azure Data Explorer 會為您建立事件方格訂用帳戶、事件中樞命名空間和事件中樞。否則，您必須手動建立這些資源，以確保建立數據連線。請參閱手動建立事件方格擷取的資源

您可以選擇性地追蹤特定的事件方格主體。設定通知的篩選條件，如下所示：
- 前置詞欄位是主題的常值前置詞。當套用的模式開頭時，它可以跨越多個容器、資料夾或 Blob。不允許使用萬用字元。
  - 若要在 blob 容器上定義篩選條件，欄位必須按照以下方式設定：/blobServices/default/containers/[container prefix]。
  - 若要在 blob 前置詞 (或 Azure Data Lake Gen2) 上定義資料夾，欄位必須按照以下方式設定：/blobServices/default/containers/[container name]/blobs/[folder/blob prefix]。
- 後置詞欄位是 blob 的常值後置詞。不允許使用萬用字元。
- 區分大小寫欄位顯示前置詞和後置詞篩選條件是否區分大小寫
如需篩選事件的詳細資訊，請參閱 Blob 記憶體事件。

您可以選擇性地根據下列資訊指定 資料路由設定 。您不需要指定所有資料 路由設定。也會接受部分設定。

設定	建議的值	欄位描述
允許將數據路由傳送至其他資料庫， (多資料庫數據連線)	不允許	如果您想要覆寫與數據連線相關聯的默認目標資料庫，請切換此選項。如需資料庫路由的詳細資訊，請參閱事件路由。
資料表名稱	TestTable	您在 TestDatabase 中建立的資料表。
資料格式	JSON	支援的格式包括APACHEAVRO、Avro、CSV、JSON、ORC、PARQUET、PSV、RAW、SCSV、SOHSV、TSV、TSVE、TXT 和 W3CLOG。支援的壓縮選項為 Zip 和 Gzip。
對應名稱	TestTable_mapping	您在 TestDatabase 中建立的對應，會將傳入的資料對應至資料行名稱和 TestTable 的資料類型。如果未指定，則會自動產生衍生自數據表架構的識別數據對應。
忽略格式錯誤	忽略	如果您想要忽略 JSON 資料格式的格式錯誤，請切換此選項。

注意

數據表和對應名稱會區分大小寫。

您可以選擇性地在 [ 進階設定] 下，指定數據連線所使用的 受控識別類型 。根據預設，系統會選取 [系統指派 ]。

如果您選取 [使用者指派]，則必須手動指派受控識別。如果您選取尚未指派給叢集的使用者，則會自動指派該使用者。如需詳細資訊，請參閱設定 Azure Data Explorer 叢集的受控識別。

如果您選取 [無]，記憶體帳戶和事件中樞會透過連接字串進行驗證。不建議使用此方法。

選取 [建立]

流覽至 Azure 入口網站中的記憶體帳戶。
選取 [事件]。
在 [開始使用] 索引標籤中，選取 [Azure Data Explorer] 索引卷標。
在 [ 建立連續數據擷取 ] 圖格中，選取 [ 建立]。

選擇要將事件路由傳送至的目的地

選取您要在其中內嵌數據的叢集。
選取目標資料庫。
選取 [選取]。

建立數據連線

在表單中填寫以下資訊：

設定	建議的值	欄位描述
資料連線名稱	test-grid-connection	您想要在 Azure 資料總管中建立的連線名稱。
儲存體帳戶訂用帳戶	您的訂用帳戶識別碼	儲存體帳戶所在的訂用帳戶識別碼。
事件類型	blob 已建立或 blob 已重新命名	觸發擷取的事件類別。只有 ADLSv2 儲存體支援 blob 已重新命名。若要重新命名 Blob，請流覽至 Azure 入口網站中的 Blob，以滑鼠右鍵按兩下 Blob，然後選取 [重新命名]。支援的型別：Microsoft.Storage.BlobCreated 或 Microsoft.Storage.BlobRenamed。
儲存體帳戶	gridteststorage1	您從中存取此精靈的記憶體帳戶會自動填入。
資源建立	自動	開啟自動資源建立表示 Azure Data Explorer 會為您建立事件方格訂用帳戶、事件中樞命名空間和事件中樞。否則，您必須手動建立這些資源，以確保建立數據連線。請參閱手動建立事件方格擷取的資源

您可以選擇性地追蹤特定的事件方格主題。設定通知的篩選條件，如下所示：
- 前置詞欄位是主題的常值前置詞。套用的模式 一開始，它可以跨越多個容器、資料夾或 Blob。不允許使用萬用字元。
  - 若要在 blob 容器上定義篩選條件，欄位必須按照以下方式設定：/blobServices/default/containers/[container prefix]。
  - 若要在 blob 前置詞 (或 Azure Data Lake Gen2) 上定義資料夾，欄位必須按照以下方式設定：/blobServices/default/containers/[container name]/blobs/[folder/blob prefix]。
- 後置詞欄位是 blob 的常值後置詞。不允許使用萬用字元。
- 區分大小寫欄位顯示前置詞和後置詞篩選條件是否區分大小寫
如需篩選事件的詳細資訊，請參閱 Blob 記憶體事件。

您可以選擇性地根據下列資訊來指定 資料路由設定 。您不需要指定所有資料 路由設定。也會接受部分設定。

設定	建議的值	欄位描述
允許將數據路由傳送至其他資料庫， (多資料庫數據連線)	不允許	如果您想要覆寫與數據連線相關聯的默認目標資料庫，請切換此選項。如需資料庫路由的詳細資訊，請參閱事件路由。
資料表名稱	TestTable	您在 TestDatabase 中建立的資料表。
資料格式	JSON	支援的格式包括APACHEAVRO、Avro、CSV、JSON、ORC、PARQUET、PSV、RAW、SCSV、SOHSV、TSV、TSV、TSVE、TXT 和 W3CLOG。支援的壓縮選項為 Zip 和 Gzip。
對應名稱	TestTable_mapping	您在 TestDatabase 中建立的對應，會將傳入的資料對應至資料行名稱和 TestTable 的資料類型。如果未指定，則會自動產生衍生自數據表架構的識別數據對應。
忽略格式錯誤	忽略	如果您想要忽略 JSON 資料格式的格式錯誤，請切換此選項。

注意

數據表和對應名稱會區分大小寫。

您可以選擇性地在 [ 進階設定] 下，指定數據連線所使用的 受控識別類型 。默認會選取 [系統指派 ]。

如果您選取 [使用者指派]，則必須手動指派受控識別。如果您選取尚未指派給叢集的使用者，則會自動指派該使用者。如需詳細資訊，請參閱設定 Azure Data Explorer 叢集的受控識別。

如果您選取 [無]，記憶體帳戶和事件中樞會透過連接字串進行驗證。不建議使用此方法。

選取 [建立]。

下列範例顯示用於新增事件方格數據連線的 Azure Resource Manager 範本。您可以使用表單，在 Azure 入口網站中編輯和部署範本。

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "namespaces_eventhubns_name": {
            "type": "string",
            "defaultValue": "eventhubns",
            "metadata": {
                "description": "Specifies the event hub namespace name."
            }
        },
        "EventHubs_eventhubdemo_name": {
            "type": "string",
            "defaultValue": "eventhubdemo",
            "metadata": {
                "description": "Specifies the event hub name."
            }
        },
        "consumergroup_default_name": {
            "type": "string",
            "defaultValue": "$Default",
            "metadata": {
                "description": "Specifies the consumer group of the event hub."
            }
        },
        "StorageAccounts_storagedemo_name": {
            "type": "string",
            "defaultValue": "storagedemo",
            "metadata": {
                "description": "Specifies the storage account name"
            }
        },
        "Clusters_kustocluster_name": {
            "type": "string",
            "defaultValue": "kustocluster",
            "metadata": {
                "description": "Specifies the name of the cluster"
            }
        },
        "databases_kustodb_name": {
            "type": "string",
            "defaultValue": "kustodb",
            "metadata": {
                "description": "Specifies the name of the database"
            }
        },
        "tables_kustotable_name": {
            "type": "string",
            "defaultValue": "kustotable",
            "metadata": {
                "description": "Specifies the name of the table"
            }
        },
        "mapping_kustomapping_name": {
            "type": "string",
            "defaultValue": "kustomapping",
            "metadata": {
                "description": "Specifies the name of the mapping rule"
            }
        },
        "dataformat_type": {
            "type": "string",
            "defaultValue": "csv",
            "metadata": {
                "description": "Specifies the data format"
            }
        },
             "databaseRouting_type": {
            "type": "string",
            "defaultValue": "Single",
            "metadata": {
                "description": "The database routing for the connection. If you set the value to **Single**, the data connection will be routed to a single database in the cluster as specified in the *databaseName* setting. If you set the value to **Multi**, you can override the default target database using the *Database* EventData property."
            }
        },
        "dataconnections_kustodc_name": {
            "type": "string",
            "defaultValue": "kustodc",
            "metadata": {
                "description": "Name of the data connection to create"
            }
        },
        "subscriptionId": {
            "type": "string",
            "defaultValue": "[subscription().subscriptionId]",
            "metadata": {
                "description": "Specifies the subscriptionId of the resources"
            }
        },
        "resourceGroup": {
            "type": "string",
            "defaultValue": "[resourceGroup().name]",
            "metadata": {
                "description": "Specifies the resourceGroup of the resources"
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
                "description": "Location for all resources."
            }
        }
    },
    "variables": {
    },
    "resources": [{
            "type": "Microsoft.Kusto/Clusters/Databases/DataConnections",
            "apiVersion": "2022-02-01",
            "name": "[concat(parameters('Clusters_kustocluster_name'), '/', parameters('databases_kustodb_name'), '/', parameters('dataconnections_kustodc_name'))]",
            "location": "[parameters('location')]",
            "kind": "EventGrid",
            "properties": {
                "managedIdentityResourceId": "[resourceId('Microsoft.Kusto/clusters', parameters('clusters_kustocluster_name'))]",
                "storageAccountResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('StorageAccounts_storagedemo_name'))]",
                "eventHubResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.EventHub/namespaces/eventhubs', parameters('namespaces_eventhubns_name'), parameters('EventHubs_eventhubdemo_name'))]",
                "consumerGroup": "[parameters('consumergroup_default_name')]",
                "tableName": "[parameters('tables_kustotable_name')]",
                "mappingRuleName": "[parameters('mapping_kustomapping_name')]",
                "dataFormat": "[parameters('dataformat_type')]",
                "databaseRouting": "[parameters('databaseRouting_type')]"
            }
        }
    ]
}

使用事件方格數據連線

本節說明如何在建立 Blob 或 Blob 重新命名之後，觸發從 Azure Blob 儲存體或 Azure Data Lake Gen 2 擷取至叢集。

根據用來上傳 Blob 的記憶體 SDK 類型，選取相關的索引標籤。

Azure Blob 儲存體
Azure Data Lake

下列程式代碼範例會使用 Azure Blob 儲存體 SDK 將檔案上傳至 Azure Blob 儲存體。上傳會觸發事件方格數據連線，將數據內嵌至 Azure Data Explorer。

var azureStorageAccountConnectionString = <storage_account_connection_string>;
var containerName = <container_name>;
var blobName = <blob_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
// Create a new container if it not already exists.
var azureStorageAccount = new BlobServiceClient(azureStorageAccountConnectionString);
var container = azureStorageAccount.GetBlobContainerClient(containerName);
container.CreateIfNotExists();
// Define blob metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new BlobUploadOptions
{
    Metadata = metadata,
};
// Upload the file.
var blob = container.GetBlobClient(blobName);
blob.Upload(localFileName, uploadOptions);

注意

Azure Data Explorer 不會刪除擷取後的 Blob。使用 Azure Blob 記憶體生命週期來管理 Blob 刪除，將 Blob 保留三到五天。

下列程式代碼範例會使用 Azure Data Lake SDK 將檔案上傳至 Data Lake Storage Gen2。上傳會觸發 Event Grid 數據連線，以將數據內嵌至 Azure Data Explorer。

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var fileName = <file_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Create the filesystem.
var dataLakeFileSystemClient = dataLakeServiceClient.CreateFileSystem(fileSystemName).Value;
// Define file metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new DataLakeFileUploadOptions
{
    Metadata = metadata,
    Close = true // Note: The close option triggers the event being processed by the data connection.
};
// Upload the file.
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(fileName);
dataLakeFileClient.Upload(localFileName, uploadOptions);

注意

使用 Azure Data Lake SDK 上傳檔案時，初始檔案建立事件的大小為 0，在數據擷取期間，Azure Data Explorer 會忽略此大小。若要確保正確擷取，請將 Close 參數設定為 true。此參數會導致 upload 方法觸發 FlushAndClose 事件，指出已進行最終更新，並關閉檔案數據流。
若要減少來自事件方格的流量，並將事件擷取優化至 Azure Data Explorer，建議您篩選data.api 密鑰以排除 CreateFile 事件。這可確保篩選出大小為 0 的檔案建立事件，以避免擷取空白檔案的錯誤。如需排清的詳細資訊，請參閱 Azure Data Lake flush 方法。

重新命名 Blob

在ADLSv2中，可以重新命名目錄。不過，請務必注意，重新命名目錄不會觸發 Blob 重新命名事件，或起始目錄中所包含的 Blob 擷取。如果您想要確保在重新命名目錄之後擷取 Blob，您應該直接重新命名目錄中的個別 Blob。

下列程式代碼範例示範如何在ADLSv2儲存器帳戶中重新命名 Blob。

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var sourceFilePath = <source_file_path>;
var destinationFilePath = <destination_file_path>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Get a client to the the filesystem

var dataLakeFileSystemClient = dataLakeServiceClient.GetFileSystemClient(fileSystemName);
// Rename a file in the file system
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(sourceFilePath);
dataLakeFileClient.Rename(destinationFilePath);

注意

如果您在建立數據連線或手動建立事件方格資源時定義篩選來追蹤特定主體，這些篩選會套用至目的地檔案路徑。

注意

啟用階層命名空間功能的記憶體帳戶不支援在作業之後 CopyBlob 觸發擷取。

拿掉事件方格數據連線

若要從 Azure 入口網站移除 Event Grid 連線，請執行下列步驟：

移至您的叢集。從左側功能表中，選取 [ 資料庫]。然後，選取包含目標數據表的資料庫。
從左側功能表中，選取 [數據連線]。然後，選取相關事件方格數據連線旁的複選框。
從頂端功能表列選取 [ 刪除]。

使用 Azure 串流分析處理來自事件中樞的資料

建立 Azure Data Explorer 的事件方格數據連線

必要條件

建立事件方格資料連線

選擇要將事件路由傳送至的目的地

建立數據連線

使用事件方格數據連線

重新命名 Blob

拿掉事件方格數據連線

意見反應

意見反應

其他資源

建立 Azure Data Explorer 的事件方格數據連線

必要條件

建立事件方格資料連線

使用事件方格數據連線

拿掉事件方格數據連線

相關內容

意見反應

意見反應

其他資源