Share via

IoT Central REST API를 사용하여 조직을 관리하는 방법

  • 아티클

IoT Central REST API를 사용하면 IoT Central 애플리케이션과 통합되는 클라이언트 애플리케이션을 개발할 수 있습니다. REST API를 사용하여 IoT Central 애플리케이션에서 조직을 관리할 수 있습니다.

모든 IoT Central REST API 호출에는 권한 부여 헤더가 필요합니다. 자세히 알아보려면 IoT Central REST API 호출을 인증하고 권한을 부여하는 방법을 참조하세요.

IoT Central REST API에 대한 참조 설명서는 Azure IoT Central REST API 참조를 참조하세요.

IoT Central 애플리케이션의 조직에 대해 자세히 알아보려면 IoT Central 조직 관리를 참조하세요.

팁

Postman을 사용하여 이 문서에 설명된 REST API 호출을 사용해 볼 수 있습니다. IoT Central Postman 컬렉션을 다운로드하고 Postman으로 가져옵니다. 컬렉션에서 앱 하위 도메인 및 관리자 토큰과 같은 변수를 설정해야 합니다.

조직 REST API

IoT Central REST API를 통해 다음을 수행할 수 있습니다.

  • 애플리케이션에 조직 추가
  • ID로 조직 가져오기
  • 애플리케이션에서 조직 업데이트
  • 애플리케이션에서 조직 목록 가져오기
  • 애플리케이션에서 조직 삭제

조직 만들기

REST API를 사용하면 IoT Central 애플리케이션에서 조직을 만들 수 있습니다. 다음 요청을 사용하여 애플리케이션에서 조직을 만듭니다.

PUT https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31
  • organizationId - 조직의 고유 ID

다음 예에서는 IoT Central 애플리케이션에 조직을 추가하는 요청 본문을 보여 줍니다.

{
  "displayName": "Seattle",
}

요청 본문에는 다음과 같은 몇 가지 필수 필드가 있습니다.

  • @displayName: 조직의 표시 이름입니다.

요청 본문에는 몇 가지 선택적 필드가 있습니다.

  • @parent: 조직 부모의 ID입니다.

부모를 지정하지 않으면 조직은 기본 최상위 조직을 부모로 가져옵니다.

이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "id": "seattle",
  "displayName": "Seattle"
}

계층이 있는 조직을 만들 수 있습니다. 예를 들어, 부모 조직이 있는 영업 조직을 만들 수 있습니다.

다음 예에서는 IoT Central 애플리케이션에 조직을 추가하는 요청 본문을 보여 줍니다.

{
  "displayName": "Sales",
  "parent":"seattle"
}

이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "id": "sales",
  "displayName": "Sales",
  "parent":"Seattle"
}

조직 가져오기

애플리케이션에서 개별 조직의 세부 정보를 검색하려면 다음 요청을 사용합니다.

GET https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "id": "seattle",
  "displayName": "Seattle",
  "parent": "washington"
}

조직 업데이트

애플리케이션에서 조직의 세부 정보를 업데이트하려면 다음 요청을 사용합니다.

PATCH https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

다음 예제에서는 조직의 부모를 업데이트하는 요청 본문을 보여 줍니다.

{
  "parent": "washington"
}

이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "id": "seattle",
  "displayName": "Seattle Sales",
  "parent": "washington"
}

조직 나열

애플리케이션에서 조직 목록을 검색하려면 다음 요청을 사용합니다.

GET https://{your app subdomain}.azureiotcentral.com/api/organizations?api-version=2022-07-31

이 요청에 대한 응답은 다음 예제와 같습니다.

{
    "value": [
        {
            "id": "washington",
            "displayName": "Washington"
        },
        {
            "id": "redmond",
            "displayName": "Redmond"
        },
        {
            "id": "bellevue",
            "displayName": "Bellevue"
        },
        {
            "id": "spokane",
            "displayName": "Spokane",
            "parent": "washington"
        },
        {
            "id": "seattle",
            "displayName": "Seattle",
            "parent": "washington"
        }
    ]
}

조직 Washington, Redmond 및 Bellevue는 자동으로 애플리케이션의 기본 최상위 조직을 부모 조직으로 갖게 됩니다.

조직 삭제

다음 요청을 사용하여 조직을 삭제합니다.

DELETE https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

조직 사용

조직을 사용하여 애플리케이션의 리소스에 대한 액세스를 관리합니다.

역할 관리

REST API를 사용하여 IoT Central 애플리케이션에 정의된 역할을 나열할 수 있습니다. 다음 요청을 사용하여 애플리케이션에서 애플리케이션 역할 및 조직 역할 ID 목록을 검색합니다. 자세한 내용은 IoT Central 조직 관리 방법을 참조하세요.

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

이 요청에 대한 응답은 애플리케이션 역할 및 조직 역할 ID를 포함하는 다음 예와 같습니다.

{
    "value": [
        {
            "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
            "displayName": "Administrator"
        },
        {
            "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
            "displayName": "Operator"
        },
        {
            "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
            "displayName": "Builder"
        },
        {
            "id": "c495eb57-eb18-489e-9802-62c474e5645c",
            "displayName": "Org Admin"
        },
        {
            "id": "b4935647-30e4-4ed3-9074-dcac66c2f8ef",
            "displayName": "Org Operator"
        },
        {
            "id": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "displayName": "Org Viewer"
        }
    ]
}

조직 계층 구조의 노드에 연결된 API 토큰 만들기

다음 요청을 사용하여 애플리케이션의 조직 계층 구조에서 노드에 연결된 API 토큰 만들기를 만듭니다.

PUT https://{your app subdomain}.azureiotcentral.com/api/apiTokens/{tokenId}?api-version=2022-07-31
  • tokenId - 토큰의 고유 ID

다음 예제에서는 IoT Central 애플리케이션에서 seattle 조직에 대한 API 토큰을 만드는 요청 본문을 보여 줍니다.

{
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ]
}

요청 본문에는 다음과 같은 몇 가지 필수 필드가 있습니다.

이름 설명
역할(role) 조직 역할 중 하나의 ID입니다.
조직 조직의 ID

이 요청에 대한 응답은 다음 예제와 같습니다.

{
    "id": "token1",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "expiry": "2023-07-07T17:05:08.407Z",
    "token": "SharedAccessSignature sr=8a0617**********************4c0d71c&sig=3RyX69G4%2FBZZnG0LXOjQv*************e8s%3D&skn=token1&se=1688749508407"
}

사용자를 조직 계층의 노드와 연결

다음 요청을 사용하여 사용자를 만들고 애플리케이션의 조직 계층 구조에 있는 노드와 연결합니다. ID 및 메일은 애플리케이션에서 고유해야 합니다.

PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

다음 요청 본문에서 role은 조직 역할 중 하나의 ID이고 organization은 조직의 ID입니다.

{
  "id": "user-001",
  "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"

}

이 요청에 대한 응답은 다음 예제와 같습니다. 역할 값은 사용자가 연결된 역할을 식별합니다.

{
    "id": "user-001",
    "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"
}

조직에 디바이스 추가 및 연결

다음 요청을 사용하여 새 디바이스를 조직과 연결합니다.

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}?api-version=2022-07-31

다음 예에서는 디바이스 템플릿에 대한 디바이스를 추가하는 요청 본문을 보여 줍니다. IoT Central 애플리케이션 UI의 디바이스 템플릿 페이지에서 template 세부 정보를 가져올 수 있습니다.

{
    "displayName": "CheckoutThermostat",
    "template": "dtmi:contoso:Thermostat;1",
    "simulated": true,
    "enabled": true,
    "organizations": [
        "seattle"
    ]
}

요청 본문에는 다음과 같은 몇 가지 필수 필드가 있습니다.

  • @displayName: 디바이스의 표시 이름입니다.
  • @enabled: 이 개체가 인터페이스임을 선언합니다.
  • @etag: 디바이스 업데이트에서 충돌을 방지하는 데 사용되는 ETag입니다.
  • simulated: 디바이스가 시뮬레이션되었나요?
  • template: 디바이스에 대한 디바이스 템플릿 정의입니다.
  • organizations: 디바이스가 속한 조직 ID 목록입니다. 현재 디바이스는 단일 조직에만 연결할 수 있습니다.

이 요청에 대한 응답은 다음 예제와 같습니다.

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true,
   "organizations": [
    "seattle"
  ]

}

디바이스 그룹을 조직에 추가 및 연결

다음 요청을 사용하여 새 디바이스 그룹을 만들고 조직과 연결합니다.

PUT https://{your app subdomain}.azureiotcentral.com/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

디바이스 그룹을 만들 때 그룹에 추가할 디바이스를 선택하는 filter를 정의합니다. filter는 디바이스 템플릿과 일치하는 모든 속성을 식별합니다. 다음 예에서는 provisioned 속성이 true인 dtmi:modelDefinition:dtdlv2 템플릿과 연결된 모든 디바이스를 포함하는 디바이스 그룹을 만듭니다.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

요청 본문에는 다음과 같은 몇 가지 필수 필드가 있습니다.

  • @displayName: 디바이스 그룹의 표시 이름입니다.
  • @filter: 이 그룹에 있어야 하는 디바이스를 정의하는 쿼리입니다.
  • description: 디바이스 그룹에 대한 간략한 요약입니다.
  • organizations: 디바이스가 속한 조직 ID 목록입니다. 현재 디바이스는 단일 조직에만 연결할 수 있습니다.

이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

다음 단계

이제 REST API로 조직을 관리하는 방법을 배웠으므로 다음 단계는 IoT Central REST API를 사용하여 데이터 내보내기를 관리하는 방법입니다.