如何建立資料登錄

發行項
04/24/2024

資料登錄服務可讓您向 Azure 地圖服務帳戶註冊 Azure 儲存體帳戶中的資料內容。資料的範例可能包括 Azure 地圖服務地理柵欄服務中使用的地理柵欄集合。另一個範例是 ZIP 檔案，其中包含 Azure 地圖服務建立工具用來建立或更新室內地圖的繪圖套件 (DWG) 或 GeoJSON 檔案。

必要條件

重要

本文章使用 us.atlas.microsoft.com 地理 URL。如果您的帳戶未在美國建立，則必須使用不同的地理 URL。如需詳細資訊，請參閱存取 Creator 服務。
在本文中的 URL 範例中，您將需要取代：
- {Azure-Maps-Subscription-key} 您的 Azure 地圖服務訂用帳戶金鑰。
- {udid} 資料登錄的使用者資料識別碼。如需詳細資訊，請參閱使用者資料識別碼。

準備在 Azure 地圖服務中註冊資料

您必須先建立包含所有必要元件的環境，才能在 Azure 地圖服務中註冊資料。您需要具有一或多個容器的儲存體帳戶，這些容器會保存您想要註冊的檔案，以及用於驗證的受控識別。本節說明如何準備 Azure 環境，以在 Azure 地圖服務中註冊資料。

建立受控識別

有兩種受控識別：系統指派和使用者指派。系統指派的受控識別生命週期與建立該受控識別的資源密切相關。使用者指派的受控識別可用於多個資源。如需詳細資訊，請參閱 Azure 資源的受控識別。

使用下列步驟來建立受控識別，並將其新增至您的 Azure 地圖服務帳戶。

系統指派
使用者指派

建立系統指派的受控識別：

在 Azure 入口網站中移至您的 Azure地圖服務帳戶。
從左側功能表中選取 [身分識別]。
將 [狀態] 切換為 [開啟]。

如需詳細資訊，請參閱 Azure 資源的受控識別。

建立容器並上傳資料檔案

將檔案新增至資料登錄之前，您必須將其上傳至 Azure 儲存體帳戶中的容器。容器類似於檔案系統中的目錄，也就是檔案在 Azure 儲存體帳戶中組織的方式。

若要在 Azure 入口網站中建立容器，請遵循下列步驟：

從 Azure 儲存體帳戶內，從瀏覽窗格中的 [資料儲存體] 區段選取 [容器]。
在 [容器] 窗格中選取 [+ 容器]，以顯示 [新增容器] 窗格。
選取 [建立] 建立容器。

建立容器之後，您就可以將檔案上傳至其中。
建立容器之後，請加以選取。
從工具列選取 [上傳]，接著選取一或多個檔案
選取上傳按鈕。

新增資料存放區

建立 Azure 儲存體帳戶並將檔案上傳至一或多個容器之後，您就可以建立將儲存體帳戶連結至 Azure 地圖服務帳戶的資料存放區。

重要

連結至 Azure 地圖服務帳戶的所有儲存體帳戶都必須位於相同的地理位置。如需詳細資訊，請參閱 Azure 地圖服務地理範圍。

注意

如果您沒有儲存體帳戶，請參閱建立儲存體帳戶。

從 Azure 地圖服務帳戶的左側功能表中選取 [資料存放區]。
選取新增按鈕。 [新增資料存放區] 畫面會出現在右側。
輸入所需的 [資料存放區識別碼]，然後從下拉式清單中選取 [訂用帳戶名稱] 和 [儲存體帳戶]。
選取 [新增]。

新的資料存放區現在會出現在資料存放區的清單中。

將角色指派給受控識別，並將其新增至資料存放區

建立受控識別和資料存放區之後，您可以將受控識別新增至資料存放區，並同時指派參與者和儲存體 Blob 資料讀取者角色。雖然您可以直接在受控識別或儲存體帳戶中將角色新增至受控識別，但您可以在資料存放區窗格中將角色與 Azure 地圖服務資料存放區直接建立關聯的同時，輕鬆執行此動作。

注意

與資料存放區相關聯的每個受控識別都需要獲授與參與者和儲存體 Blob 資料讀取者角色。如果您沒有將角色授與受控識別的必要權限，請洽詢您的 Azure 系統管理員。若要將角色指派給受控識別，並將其與資料存放區建立關聯：

從 Azure 地圖服務帳戶的左側功能表中選取 [資料存放區]。
從清單中選取一或多個資料存放區，然後選取 [指派角色]。
從下拉式清單中選取要與所選資料存放區建立關聯的 [受控識別]。
在 [要指派的角色] 下拉式清單中選取 [參與者] 和 [儲存體 Blob 資料讀取者]。
選取 [指派] 按鈕。

資料登錄屬性

有了在 Azure 地圖服務帳戶中建立的資料存放區，您就可以收集建立資料登錄所需的屬性。

您傳入 HTTP 要求的本文中有 AzureBlob 屬性，以及傳入 URL 的使用者資料識別碼。

AzureBlob

AzureBlob 是 JSON 物件，定義建立資料登錄所需的屬性。

屬性	說明
`kind`	定義要註冊的物件類型。目前，AzureBlob 是唯一支援的種類。
`dataFormat`	位於 blobUrl 之檔案的資料格式。其格式可以是空間服務的 GeoJSON 或轉換服務的 ZIP。
`msiClientId`	用來建立資料登錄之受控識別的識別碼。
`linkedResource`	在 Azure 地圖服務帳戶中註冊的資料存放區識別碼。資料存放區包含要註冊檔案的連結。
`blobUrl`	指向 AzurebBlob 位置的 URL，該檔案已匯入至您的容器。

下列兩節提供如何取得要用於 msiClientId、blobUrl 屬性之值的詳細資料。

msiClientId 屬性

msiClientId 屬性是用來建立資料登錄之受控識別的識別碼。有兩種受控識別：系統指派和使用者指派。系統指派的受控識別生命週期與建立該受控識別的資源密切相關。使用者指派的受控識別可用於多個資源。如需詳細資訊，請參閱 Azure 資源的受控識別。

系統指派
使用者指派

使用系統指派的受控識別時，您不需要提供 msiClientId 屬性的值。當 msiClientId 為 null 時，資料登錄服務會自動使用 Azure 地圖服務帳戶之系統指派的身分識別。

blobUrl 屬性

blobUrl 屬性是要註冊檔案的路徑。您可以從已新增至的容器中取得此值。資料登錄

在 Azure 入口網站中，選取您的儲存體帳戶。
在左側功能表中，選取 [容器]。
容器清單隨即出現。選取包含您要註冊檔案的容器。
容器隨即開啟，其中顯示先前上傳檔案的清單。
選取所需的檔案，然後複製 URL。

使用者資料識別碼

資料登錄的使用者資料識別碼 (udid) 是使用者定義的 GUID，必須符合下列 RegEx 模式：

^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

提示

udid 是建立資料登錄時必須提供的使用者定義 GUID。如果您想要確定您有全域唯一識別碼 (GUID)，請考慮執行 GUID 產生工具來建立它，例如Guidgen.exe命令列程式 (Visual Studio)。

建立資料登錄

既然您的儲存體帳戶已透過資料存放區將所需的檔案連結至 Azure 地圖服務帳戶，並已收集所有必要的屬性，現在您已準備好使用資料登錄 API 來註冊這些檔案。如果您的 Azure 儲存體帳戶中有多個要註冊的檔案，則必須針對每個檔案執行註冊要求。udid

注意

可以向 Azure 地圖服務資料存放區註冊的檔案大小上限為 1 GB。

若要建立資料登錄：

系統指派
使用者指派

提供參考 HTTP 要求本文中要新增至資料登錄之儲存體帳戶所需的資訊。資訊必須是 JSON 格式，且包含下列欄位：
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
注意

使用系統指派的受控識別時，如果您在 HTTP 要求中提供 msiClientId 屬性的值，就會收到錯誤。

如需 HTTP 要求本文中所需屬性的詳細資訊，請參閱資料登錄屬性。
準備好 HTTP 要求的本文之後，請執行下列 HTTP PUT 要求：
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
如需 udid 屬性的詳細資訊，請參閱使用者資料識別碼。
從回應標頭複製 Operation-Location 索引鍵的值。

提供參考 HTTP 要求本文中要新增至資料登錄之儲存體帳戶所需的資訊。資訊必須是 JSON 格式，且包含下列欄位：
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "{The client ID of the managed identity}",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
注意

使用使用者指派的受控識別時，如果您沒有在 HTTP 要求中提供 msiClientId 屬性的值，就收到錯誤。

如需 HTTP 要求本文中所需屬性的詳細資訊，請參閱資料登錄屬性。
準備好 HTTP 要求的本文之後，請執行下列 HTTP PUT 要求：
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
如需 udid 屬性的詳細資訊，請參閱使用者資料識別碼。
從回應標頭複製 Operation-Location 索引鍵的值。

提示

如果先前註冊的檔案內容已修改，其資料驗證將會失敗，且在重新註冊之前，將無法在 Azure 地圖服務中使用。若要重新註冊檔案，請重新執行註冊要求，並傳入用來建立原始註冊的相同 AzureBlob。 Operation-Location 索引鍵的值是您將用來檢查下一節中資料登錄建立狀態的狀態 URL，其中包含取得作業 API 所使用的作業識別碼。

注意

Operation-Location 索引鍵的值不會包含 subscription-key，您將必須在使用它來檢查資料登錄建立狀態時，將其新增至要求 URL。

檢查資料登錄建立狀態

若要 (選擇性地) 檢查資料登錄建立流程的狀態，請輸入您在 [建立資料登錄] 區段中複製的狀態 URL，並將您的訂用帳戶金鑰新增為查詢字串參數。要求看起來應該類似下列 URL：

https://us.atlas.microsoft.com/dataRegistries/operations/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Primary-Subscription-key}

取得資料登錄中所有檔案的清單

使用清單要求來取得 Azure 地圖服務帳戶中註冊的所有檔案清單：

https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}

下列範例示範三個可能的狀態：已完成、執行中和失敗：

{
  "value": [
    {
      "udid": "f6495f62-94f8-0ec2-c252-45626f82fcb2",
      "description": "Contoso Indoor Design",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "zip",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path1.zip",
        "sizeInBytes": 29920,
        "contentMD5": "CsFxZ2YSfxw3cRPlqokV0w=="
      },
      "status": "Completed"
    },
    {
      "udid": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path2.geojson",
        "sizeInBytes": 1339
      },
      "status": "Running"
    },
    {
      "udid": "7c1288fa-2058-4a1b-b68f-13a6h5af7d7c",
      "description": "Contoso Geofence GeoJSON",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path3.geojson",
        "sizeInBytes": 1650,
        "contentMD5": "rYpEfIeLbWZPyaICGEGy3A=="
      },
      "status": "Failed",
      "error": {
        "code": "ContentMD5Mismatch",
        "message": "Actual content MD5: sOJMJvFParkSxBsvvrPOMQ== doesn't match expected content MD5: CsFxZ2YSfxw3cRPlqokV0w==."
      }
    }
  ]
}

執行清單要求時傳回的資料類似於建立登錄時提供的資料，其中包含一些額外項目：

property	description
contentMD5	從要註冊檔案的內容建立的 MD5 雜湊。如需詳細資訊，請參閱資料驗證
sizeInBytes	以位元組為單位的內容大小。

取代資料登錄

如果您需要以另一個檔案取代先前註冊的檔案，請重新執行註冊要求，並傳入用來建立原始註冊的相同 AzureBlob，但 blobUrl 除外。必須修改 BlobUrl 才能指向新的檔案。

資料驗證

當您使用資料登錄 API 在 Azure 地圖服務中註冊檔案時，會從檔案的內容建立 MD5 雜湊，並將其編碼為 128 位元指紋，然後將其作為 contentMD5 屬性儲存在 AzureBlob 中。儲存在 contentMD5 屬性中的 MD5 雜湊是用來確保檔案的資料完整性。由於 MD5 雜湊演算法一律會產生相同的輸出，因此資料驗證流程可以在針對 Azure 儲存體帳戶中的檔案雜湊進行註冊時，比較檔案的 contentMD5 屬性，以檢查檔案是否完整且未經修改。如果雜湊不相同，驗證就會失敗。如果基礎儲存體帳戶中的檔案變更，驗證就會失敗。如果您需要修改已在 Azure 地圖服務中註冊的檔案內容，則必須再次註冊。