데이터 레지스트리를 만드는 방법

아티클
02/23/2024

데이터 레지스트리 서비스를 사용하면 Azure Maps 계정을 사용하여 Azure Storage 계정의 데이터 콘텐츠를 등록할 수 있습니다. 데이터의 예로는 Azure Maps 지오펜싱 서비스에 사용되는 지오펜스 컬렉션이 포함될 수 있습니다. 또 다른 예로는 Azure Maps Creator가 실내 맵을 만들거나 업데이트하는 데 사용하는 그리기 패키지(DWG) 또는 GeoJSON 파일이 포함된 ZIP 파일이 있습니다.

필수 조건

Important

이 문서에서는 us.atlas.microsoft.com 지리적 URL을 사용합니다. 사용자의 계정이 미국에서 만들어지지 않은 경우 다른 지리적 URL을 사용해야 합니다. 자세한 내용은 Creator 서비스에 대한 액세스를 참조하세요.
이 문서의 URL 예제에서는 다음을 바꿔야 합니다.
- Azure Maps 구독 키를 사용하는 {Azure-Maps-Subscription-key}.
- {udid}를 데이터 레지스트리의 사용자 데이터 ID로 바꿉니다. 자세한 내용은 사용자 데이터 ID를 참조하세요.

Azure Maps에 데이터 등록 준비

Azure Maps에 데이터를 등록하려면 먼저 필요한 모든 구성 요소가 포함된 환경을 만들어야 합니다. 등록하려는 파일을 보관하고 인증을 위해 ID를 관리하는 하나 이상의 컨테이너가 있는 스토리지 계정이 필요합니다. 이 섹션에서는 Azure Maps에 데이터를 등록하기 위해 Azure 환경을 준비하는 방법을 설명합니다.

관리 ID 만들기

관리 ID에는 시스템 할당 및 사용자 할당의 두 가지 유형이 있습니다. 시스템 할당 관리 ID의 수명 주기는 해당 ID를 생성한 리소스에 연결되어 있습니다. 사용자가 할당한 관리 ID는 여러 리소스에서 사용할 수 있습니다. 자세한 내용은 Azure 리소스에 대한 ID 관리를 참조하세요.

다음 단계에서 관리 ID를 만들고 이를 Azure Maps 계정에 추가합니다.

system-assigned
user-assigned

시스템에서 할당한 관리 ID 만들기:

Azure Portal에서 Azure Maps 계정으로 이동합니다.
왼쪽 메뉴에서 ID를 선택합니다.
상태를 켜기로 전환합니다.

자세한 내용은 Azure 리소스에 대한 ID 관리를 참조하세요.

컨테이너 만들기 및 데이터 파일 업로드

데이터 레지스트리에 파일을 추가하기 전에 해당 파일을 Azure Storage 계정의 컨테이너에 업로드해야 합니다. 컨테이너는 파일 시스템의 디렉터리와 유사하며 Azure Storage 계정에서 파일이 구성되는 방식입니다.

Azure Portal에서 컨테이너를 만들려면 다음 단계를 수행합니다.

Azure Storage 계정 내 탐색 창의 데이터 스토리지 섹션에서 컨테이너를 선택합니다.
컨테이너 창에서 + 컨테이너를 선택하면 새 컨테이너 창이 나타납니다.
만들기를 선택하여 컨테이너를 만듭니다.

컨테이너가 만들어지면 해당 컨테이너에 파일을 업로드할 수 있습니다.
컨테이너가 만들어지면 선택합니다.
도구 모음에서 업로드를 선택하고 하나 이상의 파일을 선택합니다.
업로드 버튼을 선택합니다.

데이터 저장소 추가

하나 이상의 컨테이너에 업로드된 파일을 사용하여 Azure Storage 계정을 만들었으면 스토리지 계정을 Azure Maps 계정에 연결하는 데이터 저장소를 만들 준비가 된 것입니다.

Important

Azure Maps 계정에 연결된 모든 스토리지 계정은 동일한 지리적 위치에 있어야 합니다. 자세한 내용은 Azure Maps 서비스 지리적 범위를 참조하세요.

참고 항목

스토리지 계정이 없으면 스토리지 계정 만들기를 참조하세요.

Azure Maps 계정의 왼쪽 메뉴에서 데이터 저장소를 선택합니다.
추가 단추를 선택합니다. 오른쪽에 데이터 저장소 추가 화면이 나타납니다.
원하는 데이터 저장소 ID를 입력한 다음 드롭다운 목록에서 구독 이름 및 스토리지 계정을 선택합니다.
추가를 선택합니다.

이제 새 데이터 저장소가 데이터 저장소 목록에 나타납니다.

관리 ID에 역할을 할당하고 데이터 저장소에 추가

관리 ID와 데이터 저장소가 만들어지면 관리 ID를 데이터 저장소에 추가하고 동시에 기여자 및 Storage Blob 데이터 읽기 권한자 역할을 할당할 수 있습니다. 관리 ID 또는 스토리지 계정에서 직접 관리 ID에 역할을 추가할 수 있지만 데이터 저장소 창에서 직접 Azure Maps 데이터 저장소와 동시에 연결하는 동시에 쉽게 수행할 수 있습니다.

참고 항목

데이터 저장소와 연결된 각 관리 ID에는 기여자 및 Storage Blob 데이터 읽기 권한자 역할이 부여되어야 합니다. 관리 ID에 역할을 부여하는 데 필요한 권한이 없는 경우 Azure 관리자에게 문의하세요. 관리 ID에 역할을 할당하고 데이터 저장소와 연결하려면 다음 안내를 따릅니다.

Azure Maps 계정의 왼쪽 메뉴에서 데이터 저장소를 선택합니다.
목록에서 하나 이상의 데이터 저장소를 선택한 다음 역할 할당을 수행합니다.
드롭다운 목록에서 선택한 데이터 저장소에 연결할 관리 ID를 선택합니다.
할당할 역할 드롭다운 목록에서 기여자와 Storage Blob 데이터 읽기 권한자를 모두 선택합니다.
할당 단추를 선택합니다.

데이터 레지스트리 속성

Azure Maps 계정에 데이터 저장소를 만들면 데이터 레지스트리를 만드는 데 필요한 속성을 수집할 수 있습니다.

HTTP 요청 본문에 전달하는 AzureBlob 속성과 URL에 전달되는 사용자 데이터 ID가 있습니다.

AzureBlob

AzureBlob는 데이터 레지스트리를 만드는 데 필요한 속성을 정의하는 JSON 개체입니다.

속성	설명
`kind`	등록되는 개체의 형식을 정의합니다. 현재 AzureBlob이 지원되는 유일한 종류입니다.
`dataFormat`	blobUrl에 있는 파일의 데이터 서식입니다. 형식은 공간 서비스의 경우 GeoJSON, 변환 서비스의 경우 ZIP일 수 있습니다.
`msiClientId`	데이터 레지스트리를 만드는 데 사용되는 관리 ID의 ID입니다.
`linkedResource`	Azure Maps 계정에 등록된 데이터 저장소의 ID입니다. 데이터 저장소에는 등록 중인 파일에 대한 링크가 포함되어 있습니다.
`blobUrl`	컨테이너로 가져온 파일인 AzurebBlob의 위치를 가리키는 URL입니다.

다음 두 섹션에서는 msiClientId, blobUrl 속성에 사용할 값을 가져오는 방법을 자세히 설명합니다.

msiClientId 속성

msiClientId 속성은 데이터 레지스트리를 만드는 데 사용되는 관리 ID의 ID입니다. 관리 ID에는 시스템 할당 및 사용자 할당의 두 가지 유형이 있습니다. 시스템 할당 관리 ID의 수명 주기는 해당 ID를 생성한 리소스에 연결되어 있습니다. 사용자가 할당한 관리 ID는 여러 리소스에서 사용할 수 있습니다. 자세한 내용은 Azure 리소스에 대한 ID 관리를 참조하세요.

system-assigned
user-assigned

시스템 할당 관리 ID를 사용하는 경우 msiClientId 속성 값을 제공할 필요가 없습니다. 데이터 레지스트리 서비스는 msiClientId가 null인 경우 Azure Maps 계정의 시스템 할당 ID를 자동으로 사용합니다.

blobUrl 속성

blobUrl 속성은 등록되는 파일의 경로입니다. 이 값은 추가된 컨테이너에서 가져올 수 있습니다. 데이터 레지스트리

Azure Portal에서 스토리지 계정을 선택합니다.
왼쪽 메뉴에서 컨테이너를 선택합니다.
컨테이너 목록이 나타납니다. 등록하려는 파일이 포함된 컨테이너를 선택합니다.
컨테이너가 열리고 이전에 업로드된 파일 목록이 표시됩니다.
원하는 파일을 선택한 후 URL을 복사합니다.

사용자 데이터 ID

데이터 레지스트리의 사용자 데이터 ID(udid)는 다음 Regex 패턴을 준수해야 하는 사용자 정의 GUID입니다.

^[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(Globally Unique Identifier)가 있는지 확인하려면 Guidgen.exe 명령줄 프로그램( Visual Studio에서 사용 가능)과 같은 GUID 생성 도구를 실행하여 만드는 것이 좋습니다.

데이터 레지스트리 만들기

이제 데이터 저장소를 통해 Azure Maps 계정에 원하는 파일이 연결된 스토리지 계정이 있고 모든 필수 속성을 수집했으므로 데이터 레지스트리 API를 사용하여 해당 파일을 등록할 준비가 되었습니다. Azure Storage 계정에 등록하려는 파일이 여러 개 있는 경우 각 파일(udid)에 대해 등록 요청을 실행해야 합니다.

참고 항목

Azure Maps 데이터 저장소에 등록할 수 있는 파일의 최대 크기는 1GB입니다.

데이터 레지스트리를 만들려면:

system-assigned
user-assigned

HTTP 요청 본문의 데이터 레지스트리에 추가되는 스토리지 계정을 참조하는 데 필요한 정보를 제공합니다. 정보는 JSON 형식이어야 하며 다음 필드를 포함해야 합니다.
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
참고 항목

시스템 할당 관리 ID를 사용할 때 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 속성에 대한 자세한 내용은 사용자 데이터 ID를 참조하세요.
응답 헤더에서 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"
    }
}
```
참고 항목

사용자 할당 관리 ID를 사용할 때 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 속성에 대한 자세한 내용은 사용자 데이터 ID를 참조하세요.
응답 헤더에서 Operation-Location 키의 값을 복사합니다.

팁

이전에 등록된 파일의 콘텐츠가 수정되면 해당 파일은 데이터 유효성 검사에 실패하고 다시 등록될 때까지 Azure Maps에서 사용할 수 없습니다. 파일을 다시 등록하려면 등록 요청을 다시 실행하고 원래 등록을 만드는 데 사용한 것과 동일한 AzureBlob을 전달합니다. Operation-Location 키의 값은 다음 섹션에서 데이터 레지스트리 만들기 상태를 확인하는 데 사용할 상태 URL이며, 여기에는 작업 가져오기 API에서 사용하는 작업 ID가 포함됩니다.

참고 항목

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 Maps 계정에 등록된 모든 파일 목록을 가져오려면 목록 요청을 사용합니다.

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==."
      }
    }
  ]
}

목록 요청을 실행할 때 반환되는 데이터는 몇 가지 추가 사항이 포함된 레지스트리를 만들 때 제공되는 데이터와 유사합니다.

속성	description
contentMD5	등록되는 파일의 콘텐츠에서 만들어진 MD5 해시입니다. 자세한 내용은 데이터 유효성을 참조하세요.
sizeInBytes	콘텐츠의 크기(바이트)입니다.

데이터 레지스트리 바꾸기

이전에 등록된 파일을 다른 파일로 바꿔야 하는 경우 등록 요청을 다시 실행하고 blobUrl을 제외하고 원래 등록을 만드는 데 사용된 것과 동일한 AzureBlob을 전달합니다. 새 파일을 가리키도록 BlobUrl을 수정해야 합니다.

데이터 유효성 검사

데이터 레지스트리 API를 사용하여 Azure Maps에 파일을 등록하면 파일 콘텐츠에서 MD5 해시가 만들어져 이를 128비트 지문으로 인코딩하고 AzureBlob에 contentMD5 속성으로 저장합니다. contentMD5 속성에 저장된 MD5 해시는 파일의 데이터 무결성을 보장하는 데 사용됩니다. MD5 해시 알고리즘은 동일한 입력에 대해 항상 동일한 출력을 생성하므로 데이터 유효성 검사 프로세스는 파일이 등록되었을 때 파일의 contentMD5 속성을 Azure Storage 계정의 파일 해시와 비교하여 파일이 손상되지 않았으며 수정되지 않았는지 확인할 수 있습니다. 해시가 동일하지 않으면 유효성 검사가 실패합니다. 기본 스토리지 계정의 파일이 변경되면 유효성 검사가 실패합니다. Azure Maps에 등록된 파일의 콘텐츠를 수정해야 하는 경우 다시 등록해야 합니다.

데이터 레지스트리를 만드는 방법

필수 조건

Azure Maps에 데이터 등록 준비

관리 ID 만들기

컨테이너 만들기 및 데이터 파일 업로드

데이터 저장소 추가

관리 ID에 역할을 할당하고 데이터 저장소에 추가

데이터 레지스트리 속성

AzureBlob

msiClientId 속성

blobUrl 속성

사용자 데이터 ID

데이터 레지스트리 만들기

데이터 레지스트리 만들기 상태 확인

데이터 레지스트리의 모든 파일 목록 가져오기

데이터 레지스트리 바꾸기

데이터 유효성 검사

추가 리소스