使用 Azure 數據總管 Go SDK 內嵌數據

發行項
11/23/2024

Azure 資料總管是快速及可調整的資料探索服務，以取得記錄和遙測資料。它提供 Go SDK 用戶端連結庫，以便與 Azure 數據總管服務互動。您可以使用 Go SDK 在 Azure 資料總管叢集中內嵌、控制及查詢數據。

在本文中，您會先在測試叢集中建立數據表和數據對應。接著，您會使用 Go SDK 將擷取佇列至叢集，並驗證結果。

必要條件

Microsoft帳戶或Microsoft Entra 使用者身分識別。不需要 Azure 訂用帳戶。
Azure 資料總管叢集和資料庫。建立叢集和資料庫。
安裝 Git。
使用下列 Go SDK 最低需求安裝 Go。
建立應用程式註冊，並將許可權授與資料庫。儲存用戶端識別碼和客戶端密碼以供稍後使用。

安裝 Go SDK

當您執行 [使用 Go 模組的範例應用程式] 時，會自動安裝 Azure 數據總管 Go SDK。如果您為另一個應用程式安裝 Go SDK，請建立 Go 模組並擷取 Azure 資料總管套件（使用 go get），例如：

go mod init foo.com/bar
go get github.com/Azure/azure-kusto-go/kusto

套件相依性將會新增至 go.mod 檔案。在 Go 應用程式中使用它。

檢閱程式碼

此檢閱程式代碼區段是選擇性的。如果您想要瞭解程式代碼的運作方式，您可以檢閱下列代碼段。或是，您可以直接跳到執行應用程式。

驗證

程序在執行任何作業之前，必須先向 Azure 數據總管服務進行驗證。

auth := kusto.Authorization{Config: auth.NewClientCredentialsConfig(clientID, clientSecret, tenantID)}
client, err := kusto.New(kustoEndpoint, auth)

kusto 的實例。授權是使用服務主體認證所建立。然後用來建立 kusto。用戶端具有 New 函式，也接受叢集端點。

建立資料表

create table 命令是由 Kusto 語句表示。 Mgmt 函式可用來執行管理命令。它用來執行命令來建立數據表。

func createTable(kc *kusto.Client, kustoDB string) {
  _, err := kc.Mgmt(context.Background(), kustoDB, kusto.NewStmt(createTableCommand))
  if err != nil {
    log.Fatal("failed to create table", err)
  }
  log.Printf("Table %s created in DB %s\n", kustoTable, kustoDB)
}

提示

Kusto 語句預設為常數，以提升安全性。 NewStmt 接受字串常數。 UnsafeStmt API 允許使用非常數語句區段，但不建議使用。

Kusto create table 命令如下所示：

.create table StormEvents (StartTime: datetime, EndTime: datetime, EpisodeId: int, EventId: int, State: string, EventType: string, InjuriesDirect: int, InjuriesIndirect: int, DeathsDirect: int, DeathsIndirect: int, DamageProperty: int, DamageCrops: int, Source: string, BeginLocation: string, EndLocation: string, BeginLat: real, BeginLon: real, EndLat: real, EndLon: real, EpisodeNarrative: string, EventNarrative: string, StormSummary: dynamic)

建立對應

擷取期間會使用數據對應，將內送數據對應至 Azure 數據總管數據表內的數據行。如需詳細資訊，請參閱數據對應。使用具有資料庫名稱和適當命令的函式， Mgmt 建立對應的方式與數據表相同。範例的 GitHub 存放庫中提供完整的命令。

func createMapping(kc *kusto.Client, kustoDB string) {
  _, err := kc.Mgmt(context.Background(), kustoDB, kusto.NewStmt(createMappingCommand))
  if err != nil {
    log.Fatal("failed to create mapping - ", err)
  }
  log.Printf("Mapping %s created\n", kustoMappingRefName)
}

內嵌資料

擷取是使用來自現有 Azure Blob 儲存體容器的檔案排入佇列。

func ingestFile(kc *kusto.Client, blobStoreAccountName, blobStoreContainer, blobStoreToken, blobStoreFileName, kustoMappingRefName, kustoDB, kustoTable string) {
  kIngest, err := ingest.New(kc, kustoDB, kustoTable)
  if err != nil {
    log.Fatal("failed to create ingestion client", err)
  }
  blobStorePath := fmt.Sprintf(blobStorePathFormat, blobStoreAccountName, blobStoreContainer, blobStoreFileName, blobStoreToken)
  err = kIngest.FromFile(context.Background(), blobStorePath, ingest.FileFormat(ingest.CSV), ingest.IngestionMappingRef(kustoMappingRefName, ingest.CSV))

  if err != nil {
    log.Fatal("failed to ingest file", err)
  }
  log.Println("Ingested file from -", blobStorePath)
}

擷取用戶端是使用內嵌建立的。新增。 FromFile 函式用來參考 Azure Blob 儲存體 URI。對應參考名稱和數據類型會以 FileOption 的形式傳遞。

執行應用程式

從 GitHub 複製範例程式代碼：

git clone https://github.com/Azure-Samples/Azure-Data-Explorer-Go-SDK-example-to-ingest-data.git
cd Azure-Data-Explorer-Go-SDK-example-to-ingest-data

從執行此代碼段中 main.go所見的範例程式代碼：
```
func main {
    ...
    dropTable(kc, kustoDB)
    createTable(kc, kustoDB)
    createMapping(kc, kustoDB)
    ingestFile(kc, blobStoreAccountName, blobStoreContainer, blobStoreToken, blobStoreFileName, kustoMappingRefName, kustoDB, kustoTable)
    ...
}
```
提示

若要嘗試不同的作業組合，您可以在中 main.go取消批注/批注個別函式。

當您執行範例程式代碼時，會執行下列動作：
1. 卸除數據表：StormEvents卸除數據表（如果有的話）。
2. 數據表建立： StormEvents 建立數據表。
3. 對應建立： StormEvents_CSV_Mapping 建立對應。
4. 檔案擷取：CSV 檔案（Azure Blob 儲存體）已排入佇列以擷取。

若要建立服務主體以進行驗證，請使用 Azure CLI 搭配 az ad sp create-for-rbac 命令。以程式將使用的環境變數形式，使用叢集端點和資料庫名稱來設定服務主體資訊：

export AZURE_SP_CLIENT_ID="<replace with appID>"
export AZURE_SP_CLIENT_SECRET="<replace with password>"
export AZURE_SP_TENANT_ID="<replace with tenant>"
export KUSTO_ENDPOINT="https://<cluster name>.<azure region>.kusto.windows.net"
export KUSTO_DB="name of the database"

執行程式：

go run main.go

您將會收到類似的輸出：

Connected to Azure Data Explorer
Using database - testkustodb
Failed to drop StormEvents table. Maybe it does not exist?
Table StormEvents created in DB testkustodb
Mapping StormEvents_CSV_Mapping created
Ingested file from - https://kustosamples.blob.core.windows.net/samplefiles/StormEvents.csv

驗證和疑難解答

等候 5 到 10 分鐘，等候佇列擷取排程擷取程式，並將數據載入 Azure 數據總管。

登入 https://dataexplorer.azure.com 併連線到您的叢集。然後執行下列命令以取得數據表中的 StormEvents 記錄計數。
```
StormEvents | count
```
在資料庫中執行下列命令，以查看過去四小時內是否有任何擷取失敗。在執行之前，請先取代資料庫名稱。
```
.show ingestion failures
| where FailedOn > ago(4h) and Database == "<DatabaseName>"
```

執行下列命令，以檢視過去四小時內所有擷取作業的狀態。在執行之前，請先取代資料庫名稱。

.show operations
| where StartedOn > ago(4h) and Database == "<DatabaseName>" and Operation == "DataIngestPull"
| summarize arg_max(LastUpdatedOn, *) by OperationId

清除資源

如果您打算遵循我們的其他文章，請保留您所建立的資源。如果沒有，請在資料庫中執行下列命令來卸除 StormEvents 數據表。

.drop table StormEvents

後續步驟

撰寫查詢

共用方式為