設定 Azure Data Lake Storage Gen2 的數據流端點

發行項
11/20/2024

重要

此頁面包含使用 Kubernetes 部署指令清單來管理 Azure IoT Operations 元件的指示，其處於預覽狀態。這項功能隨附數個限制，不應用於生產工作負載。

請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

若要將數據傳送至 Azure IoT 作業中的 Azure Data Lake Storage Gen2，您可以設定數據流端點。此組態可讓您指定目的地端點、驗證方法、數據表和其他設定。

必要條件

Azure IoT 作業的實例
Azure Data Lake Storage Gen2 帳戶
記憶體帳戶中預先建立的記憶體容器

將許可權指派給受控識別

若要設定 Azure Data Lake Storage Gen2 的數據流端點，建議您使用使用者指派或系統指派的受控識別。這種方法是安全的，而且不需要手動管理認證。

建立 Azure Data Lake Storage Gen2 之後，您必須將角色指派給 Azure IoT Operations 受控識別，以授與寫入記憶體帳戶的許可權。

如果使用系統指派的受控識別，請在 Azure 入口網站中移至您的 Azure IoT 作業實例，然後選取 [概觀]。複製 Azure IoT Operations Arc 延伸模組之後 所列的延伸模組名稱。例如， azure-iot-operations-xxxx7。您可以使用 Azure IoT Operations Arc 延伸模組的相同名稱，找到系統指派的受控識別。

然後，移至 Azure 儲存體帳戶>訪問控制（IAM）>新增角色指派。

在 [ 角色] 索引標籤上，選取適當的角色，例如 Storage Blob Data Contributor。這會為受控識別提供寫入 Azure 儲存體 Blob 容器的必要許可權。若要深入瞭解，請參閱使用 Microsoft Entra ID 授權存取 Blob。
在 [ 成員] 索引標籤上：
1. 如果使用系統指派的受控識別，針對 [指派存取權]，選取 [使用者、群組或服務主體 ] 選項，然後選取 [+ 選取成員 ]，然後搜尋 Azure IoT Operations Arc 擴充功能的名稱。
2. 如果使用使用者指派的受控識別，針對 [指派存取權] 選取 [受控識別 ] 選項，然後選取 [+ 選取成員 ]，然後搜尋針對雲端連線設定的使用者指派受控識別。

建立 Azure Data Lake Storage Gen2 的數據流端點

在 IoT 作業入口網站中，選取 [ 資料流端點] 索引標籤 。
在 [建立新的數據流端點] 下，選取 [Azure Data Lake Storage][第二代][>新增]。

輸入端點的下列設定：

設定	描述
名稱	數據流端點的名稱。
Host	Azure Data Lake Storage Gen2 端點的主機名，格式為 `<account>.blob.core.windows.net`。將帳戶佔位元取代為端點帳戶名稱。
驗證方法	用於驗證的方法。我們建議您選擇 [系統指派的受控識別] 或 [使用者指派的受控識別]。
Client ID	使用者指派受控識別的用戶端標識碼。如果使用使用者指派的受控識別，則為必要專案。
租用戶識別碼	使用者指派受控識別的租用戶標識碼。如果使用使用者指派的受控識別，則為必要專案。
存取令牌秘密名稱	包含SAS令牌的 Kubernetes 秘密名稱。如果使用存取令牌，則為必要專案。

選取 [ 套用 ] 以布建端點。

使用下列內容建立 Bicep .bicep 檔案。

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param endpointName string = '<ENDPOINT_NAME>'
param host string = 'https://<ACCOUNT>.blob.core.windows.net'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}
resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}
resource adlsGen2Endpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'DataLakeStorage'
    dataLakeStorageSettings: {
      host: host
      authentication: {
        // See available authentication methods section for method types
        // method: <METHOD_TYPE>
      }
    }
  }
}

然後，透過 Azure CLI 進行部署。

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

使用下列內容建立 Kubernetes 指令清單 .yaml 檔案。

apiVersion: connectivity.iotoperations.azure.com/v1
kind: DataflowEndpoint
metadata:
  name: <ENDPOINT_NAME>
  namespace: azure-iot-operations
spec:
  endpointType: DataLakeStorage
  dataLakeStorageSettings:
    host: https://<ACCOUNT>.blob.core.windows.net
    authentication:
      # See available authentication methods section for method types
      # method: <METHOD_TYPE>

然後將指令清單檔案套用至 Kubernetes 叢集。

kubectl apply -f <FILE>.yaml

使用存取令牌驗證

請遵循存取令牌一節中的步驟，取得記憶體帳戶的SAS令牌，並將其儲存在 Kubernetes 秘密中。

然後，建立 DataflowEndpoint 資源並指定存取令牌驗證方法。在這裡，將取代 <SAS_SECRET_NAME> 為包含 SAS 令牌和其他佔位元值的秘密名稱。

如需在作業體驗入口網站中建立秘密的步驟，請參閱存取令牌一節。

使用下列內容建立 Bicep .bicep 檔案。

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param endpointName string = '<ENDPOINT_NAME>'
param host string = 'https://<ACCOUNT>.blob.core.windows.net'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}
resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}
resource adlsGen2Endpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'DataLakeStorage'
    dataLakeStorageSettings: {
      host: host
      authentication: {
        method: 'AccessToken'
        accessTokenSettings: {
          secretRef: '<SAS_SECRET_NAME>'
        }
      }
    }
  }
}

然後，透過 Azure CLI 進行部署。

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

使用下列內容建立 Kubernetes 指令清單 .yaml 檔案。

apiVersion: connectivity.iotoperations.azure.com/v1
kind: DataflowEndpoint
metadata:
  name: <ENDPOINT_NAME>
  namespace: azure-iot-operations
spec:
  endpointType: DataLakeStorage
  dataLakeStorageSettings:
    host: https://<ACCOUNT>.blob.core.windows.net
    authentication:
      method: AccessToken
      accessTokenSettings:
        secretRef: <SAS_SECRET_NAME>

然後將指令清單檔案套用至 Kubernetes 叢集。

kubectl apply -f <FILE>.yaml

可用的驗證方法

下列驗證方法適用於 Azure Data Lake Storage Gen2 端點。

系統指派的受控識別

設定數據流端點之前，請先將角色指派給 Azure IoT Operations 受控識別，以授與寫入記憶體帳戶的許可權：

在 Azure 入口網站中，移至您的 Azure IoT 作業實例，然後選取 [概觀]。
複製 Azure IoT Operations Arc 延伸模組之後 所列的延伸模組名稱。例如， azure-iot-operations-xxxx7。
移至您需要授與許可權的雲端資源。例如，移至 Azure 儲存體帳戶>訪問控制（IAM）>新增角色指派。
在 [ 角色] 索引標籤上，選取適當的角色。
在 [成員] 索引標籤上，針對 [指派存取權]，選取 [使用者、群組或服務主體] 選項，然後選取 [+ 選取成員]，然後搜尋 Azure IoT Operations 受控識別。例如， azure-iot-operations-xxxx7。

然後，使用系統指派的受控識別設定來設定數據流端點。

在 [作業體驗數據流端點設定] 頁面中，選取 [基本] 索引標籤，然後選擇 [驗證方法>系統指派的受控識別]。

在大部分情況下，您不需要指定服務物件。未指定物件會建立受控識別，其預設物件範圍限定於您的記憶體帳戶。

dataLakeStorageSettings: {
  authentication: {
    method: 'SystemAssignedManagedIdentity'
    systemAssignedManagedIdentitySettings: {}
  }
}

dataLakeStorageSettings:
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings: {}

如果您需要覆寫系統指派的受控識別物件，您可以指定 audience 設定。

在大部分情況下，您不需要指定服務物件。未指定物件會建立受控識別，其預設物件範圍限定於您的記憶體帳戶。

dataLakeStorageSettings: {
  authentication: {
    method: 'SystemAssignedManagedIdentity'
    systemAssignedManagedIdentitySettings: {
        audience: 'https://<ACCOUNT>.blob.core.windows.net'
    }
  }
}

dataLakeStorageSettings:
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings:
      audience: https://<ACCOUNT>.blob.core.windows.net

使用者指派的受控識別

若要使用使用者指派的受控識別進行驗證，您必須先部署已啟用安全設定的 Azure IoT 作業。然後，您必須為雲端連線設定使用者指派的受控識別。若要深入瞭解，請參閱在 Azure IoT 作業部署中啟用安全設定。

設定資料流端點之前，請先將角色指派給使用者指派的受控識別，以授與寫入記憶體帳戶的許可權：

在 Azure 入口網站中，移至您需要授與許可權的雲端資源。例如，移至 Azure 儲存體帳戶>訪問控制（IAM）>新增角色指派。
在 [ 角色] 索引標籤上，選取適當的角色。
在 [成員] 索引標籤上，針對 [指派存取權]，選取 [受控識別] 選項，然後選取 [+ 選取成員]，然後搜尋使用者指派的受控識別。

然後，使用使用者指派的受控識別設定來設定數據流端點。

在 [作業體驗數據流端點設定] 頁面中，選取 [基本] 索引標籤，然後選擇 [驗證方法>使用者指派的受控識別]。

在適當的欄位中輸入使用者指派的受控識別用戶端識別碼和租用戶標識碼。

dataLakeStorageSettings: {
  authentication: {
    method: 'UserAssignedManagedIdentity'
    userAssignedManagedIdentitySettings: {
      clientId: '<ID>'
      tenantId: '<ID>'
      // Optional, defaults to 'https://storage.azure.com/.default'
      // scope: 'https://<SCOPE_URL>'
    }
  }
}

dataLakeStorageSettings:
  authentication:
    method: UserAssignedManagedIdentity
    userAssignedManagedIdentitySettings:
      clientId: <ID>
      tenantId: <ID>
      # Optional, defaults to 'https://storage.azure.com/.default'
      # scope: https://<SCOPE_URL>

在這裡，範圍是選擇性的，預設為 https://storage.azure.com/.default。如果您需要覆寫預設範圍，請透過 Bicep 或 Kubernetes 指令清單指定 scope 設定。

存取權杖

使用存取令牌是替代的驗證方法。此方法會要求您使用SAS令牌建立 Kubernetes 秘密，並在 DataflowEndpoint 資源中參考秘密。

取得 Azure Data Lake Storage Gen2 （ADLSv2）帳戶的 SAS 令牌。例如，使用 Azure 入口網站瀏覽至您的儲存體帳戶。在左側功能表上，選擇 [安全性 + 網路>共用存取簽章]。 使用以下資料表來設定必要的權限。

參數	已啟用設定
允許的服務	Blob
允許的資源類型	物件、容器
允許的權限	讀取、寫入、刪除、列出、建立

若要增強安全性並遵循最低許可權原則，您可以針對特定容器產生SAS令牌。若要防止驗證錯誤，請確定 SAS 令牌中指定的容器符合組態中的數據流目的地設定。

重要

若要使用作業體驗入口網站來管理秘密，必須先設定 Azure 金鑰保存庫並啟用工作負載身分識別，以使用安全設定來啟用 Azure IoT 作業。若要深入瞭解，請參閱在 Azure IoT 作業部署中啟用安全設定。

在 [作業體驗數據流端點設定] 頁面中，選取 [基本] 索引標籤，然後選擇 [驗證方法>存取令牌]。

在這裡，在 [同步的秘密名稱] 下，輸入秘密的名稱。此名稱用來參考數據流端點設定中的秘密，而且是儲存在 Kubernetes 叢集中的秘密名稱。

然後，在 [存取令牌密碼名稱] 底下，選取 [新增參考] 以從 Azure 金鑰保存庫新增密碼。在下一個頁面上，從 Azure 金鑰保存庫選取 [從 Azure 新增] 金鑰保存庫或 [建立新秘密] 的秘密。

如果您選擇 [ 新建]，請輸入下列設定：

設定	描述
祕密名稱	Azure 金鑰保存庫中的秘密名稱。挑選容易記住的名稱，以便稍後從清單中選取秘密。
祕密值	格式為的 `'sv=2022-11-02&ss=b&srt=c&sp=rwdlax&se=2023-07-22T05:47:40Z&st=2023-07-21T21:47:40Z&spr=https&sig=<signature>'`SAS令牌。
設定啟用日期	如果開啟，則秘密變成作用中的日期。
設定到期日期	如果開啟，則為秘密到期的日期。

若要深入瞭解秘密，請參閱在 Azure IoT 作業中建立和管理秘密。

dataLakeStorageSettings: {
  authentication: {
    method: 'AccessToken'
    accessTokenSettings: {
      secretRef: '<SAS_SECRET_NAME>'
    }
  }
}

使用 SAS 權杖建立 Kubernetes 秘密。

kubectl create secret generic <SAS_SECRET_NAME> -n azure-iot-operations \
--from-literal=accessToken='sv=2022-11-02&ss=b&srt=c&sp=rwdlax&se=2023-07-22T05:47:40Z&st=2023-07-21T21:47:40Z&spr=https&sig=<signature>'

dataLakeStorageSettings:
  authentication:
    method: AccessToken
    accessTokenSettings:
      secretRef: <SAS_SECRET_NAME>

進階設定

您可以設定 Azure Data Lake Storage Gen2 端點的進階設定，例如批處理延遲和訊息計數。

使用設定 batching 來設定訊息數目上限和訊息傳送至目的地之前的最大延遲。當您想要針對網路頻寬進行優化，並減少對目的地的要求數目時，此設定很有用。

欄位	描述	必要
`latencySeconds`	將訊息傳送至目的地之前要等候的最大秒數。預設值為 60 秒。	No
`maxMessages`	要傳送至目的地的訊息數目上限。預設值為 100000 訊息。	No

例如，若要將訊息數目上限設定為 1000，以及延遲上限為 100 秒，請使用下列設定：

在作業體驗中，選取數據流端點的 [ 進階 ] 索引標籤。

使用作業體驗來設定ADLS V2進階設定的螢幕快照。

dataLakeStorageSettings: {
  batching: {
    latencySeconds: 100
    maxMessages: 1000
  }
}

dataLakeStorageSettings:
  batching:
    latencySeconds: 100
    maxMessages: 1000

下一步

若要深入了解數據流，請參閱建立數據流。
若要查看如何使用數據流將數據傳送至 Azure Data Lake Storage Gen2 的教學課程，請參閱教學課程：將數據傳送至 Azure Data Lake Storage Gen2。

共用方式為