Compartilhar via

Como usar as APIs de gerenciamento de Gêmeos Digitais do Azure

  • Artigo

Importante

Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz das funcionalidades expandidas do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.

Para exibir a documentação do novo serviço, visite a Documentação ativa dos Gêmeos Digitais do Azure.

As APIs de gerenciamento dos Gêmeos Digitais do Azure fornecem funcionalidades eficientes para seus aplicativos de IoT. Este artigo mostra como navegar pela estrutura de API.

Resumo da API

A lista a seguir mostra os componentes das APIs de Gêmeos Digitais.

  • /spaces: essas APIs interagem com os locais físicos em sua configuração. Elas o ajudam a criar, excluir e gerenciar os mapeamentos digitais de seus locais físicos na forma de um grafo espacial.

  • /devices: essas APIs interagem com os dispositivos em sua configuração. Esses dispositivos podem gerenciar um ou mais sensores. Por exemplo, um dispositivo pode ser seu telefone, um pod do sensor Raspberry Pi, um gateway Lora e assim por diante.

  • /sensors: essas APIs ajudam você a se comunicar com os sensores associados aos seus dispositivos e seus locais físicos. os sensores gravam e enviam valores de ambiente que, em seguida, podem ser usados para manipular o seu ambiente espacial.

  • /resources: essas APIs ajudam você a configurar recursos, como um hub IoT, para sua instância dos Gêmeos Digitais.

  • /types: Essas APIs permitem associar tipos estendidos aos objetos dos Gêmeos Digitais para adicionar características específicas a esses objetos. esses tipos permitem filtrar e agrupar facilmente objetos na interface do usuário e as funções personalizadas que processam os dados de telemetria. Exemplos de tipos estendidos são DeviceType, SensorType, SensorDataType, SpaceType, SpaceSubType, SpaceBlobType, SpaceResourceType e assim por diante.

  • /onlogies: essas APIs ajudam você a gerenciar ontologias, que são coleções de tipos estendidos. As ontologias fornecem nomes para tipos de objeto conforme o espaço físico que eles representam. Por exemplo, a ontologia BACnet fornece nomes específicos para sensor types, datatypes, datasubtypes e dataunittypes. As ontologias são gerenciadas e criadas pelo serviço. Os usuários podem carregar e descarregar ontologias. Quando uma ontologia é carregada, todos os seus nomes de tipo associados estão habilitados e prontos para serem provisionados no grafo espacial.

  • /propertyKeys: você pode usar essas APIs para criar propriedades personalizadas para seus espaços, dispositivos, usuários e sensores. Essas propriedades são criadas como pares chave/valor. Você pode definir o tipo de dados para essas propriedades definindo o PrimitiveDataType. Por exemplo, você pode definir uma propriedade chamada BasicTemperatureDeltaProcessingRefreshTime do tipo uint de sensores e, em seguida, atribuir um valor para essa propriedade para cada um dos seus sensores. Você também pode adicionar restrições para esses valores ao criar a propriedade, como os intervalos Mín e Máx, bem como os valores permitidos como ValidationData.

  • /matchers: essas APIs permitem que você especifique as condições que deseja avaliar de seus dados de dispositivo de entrada. Consulte este artigo para obter mais informações.

  • /userDefinedFunctions: essas APIs permitem que você crie, exclua ou atualize uma função personalizada que será executada quando ocorrerem condições definidas pelos correspondentes , para processar dados provenientes da configuração. Veja neste artigo para obter mais informações sobre essas funções personalizadas, também chamadas de funções definidas pelo usuário.

  • /endpoints: essas APIs permitem que você crie pontos de extremidade para que sua solução de Gêmeos Digitais possa se comunicar com outros serviços do Azure para armazenamento e análise de dados. Leia este artigo para obter mais informações.

  • /keyStores: essas APIs permitem que você gerencie repositórios de chaves de segurança para seus espaços. Esses armazenamentos podem manter uma coleção de chaves de segurança e permitem que você recupere facilmente as chaves válidas mais recentes.

  • /users: Essas APIs permitem que você associe usuários aos seus espaços para localizar esses indivíduos quando necessário.

  • /system: essas APIs permitem que você gerencie as configurações em todo o sistema, como os tipos padrão de espaços e sensores.

  • /roleAssignments: essas APIs permitem associar funções a entidades como ID de usuário, ID de função definida pelo usuário etc. Cada atribuição de função inclui a ID da entidade a ser associada, o tipo de entidade, a ID da função a ser associada, a ID do locatário e um caminho que define o limite superior do recurso que a entidade pode acessar com essa associação. Leia este artigo para obter mais informações.

Navegação de API

As APIs de Gêmeos Digitais oferecem suporte para filtragem e navegação em todo o grafo espacial usando os seguintes parâmetros:

  • spaceId: a API filtrará os resultados pela ID de espaço fornecida. Além disso, o sinalizador booliano useParentSpace é aplicável às APIs /espaces, o que indica que a ID do espaço determinada se refere ao espaço pai, em vez de ao espaço atual.

  • minLevel e maxLevel: os espaços raiz são considerados no nível 1. Espaço com espaço pai no nível n estão no nível n+1. Com esses valores definidos, você pode filtrar os resultados em níveis específicos. Esses são os valores inclusivos quando definidos. Dispositivos, sensores e outros objetos são considerados como estando no mesmo nível que seu espaço de mais próximo. Para obter todos os objetos em um determinado nível, defina minLevel e maxLevel para o mesmo valor.

  • minRelative e maxRelative: quando esses filtros são dados, o nível correspondente é relativo ao nível da ID de espaço fornecida:

    • O nível relativo 0 é do mesmo nível que a ID do espaço determinada.
    • O nível relativo 1 representa espaços no mesmo nível que os filhos da ID do espaço determinada. O nível relativo n representa espaços menores do que o espaço especificado por níveis n.
    • O nível relativo -1 representa espaços no mesmo nível que o espaço do pai do espaço especificado.

  • passagem: permite que você percorra em qualquer direção de uma determinada ID de espaço, conforme especificado pelos seguintes valores.

    • Nenhum: esse valor padrão filtra para a ID de espaço fornecida.
    • Abaixo: isso filtra pela ID de espaço fornecida e seus descendentes.
    • Up: Isso filtra pela ID de espaço fornecida e seus ancestrais.
    • Span: Isso filtra uma parte horizontal do grafo espacial, no mesmo nível que a ID de espaço fornecida. Precisa que s minRelative ou maxRelative esteja definido como true.

Exemplos

A lista a seguir mostra alguns exemplos de navegação pelas APIs /devices. Observe que o espaço reservado YOUR_MANAGEMENT_API_URL refere-se ao URI das APIs de Gêmeos Digitais no formato https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0/, em que YOUR_INSTANCE_NAME é o nome da sua instância de Gêmeos Digitais do Azure e YOUR_LOCATION é a região em que a instância está hospedada.

  • YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 retorna todos os dispositivos conectados aos espaços raiz.
  • YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 retorna todos os dispositivos conectados aos espaços de níveis 2, 3 ou 4.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId retorna todos os dispositivos diretamente anexados ao mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down retorna todos os dispositivos anexados ao mySpaceId ou um de seus descendentes.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true retorna todos os dispositivos anexados a descendentes do mySpaceId, excluindo mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true retorna todos os dispositivos anexados a filhos imediatos do mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true retorna todos os dispositivos anexados a um dos ancestrais mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 retorna todos os dispositivos anexados a descendentes do mySpaceId que estão no nível menor ou igual a 5.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true retorna todos os dispositivos anexados a espaços que estão no mesmo nível como mySpaceId.

Suporte a OData

A maioria das APIs que retorna coleções, como uma chamada GET em /spaces, dá suporte ao seguinte subconjunto dos genéricos das opções de consulta do sistema OData:

  • $filter
  • $orderby
  • $top
  • $skip – se você pretende exibir toda a coleção, deve solicitá-la como um conjunto inteiro em uma única chamada e, em seguida, executar a paginação em seu aplicativo.

Observação

Atualmente, não há suporte para algumas opções OData (como opções de consulta $count, $expand e $search).

Exemplos

A lista a seguir ilustra várias consultas com sintaxe OData válida:

  • YOUR_MANAGEMENT_API_URL/devices?$top=3&$orderby=Name desc
  • YOUR_MANAGEMENT_API_URL/keystores?$filter=endswith(Description,'space')
  • YOUR_MANAGEMENT_API_URL/devices?$filter=TypeId eq 2
  • YOUR_MANAGEMENT_API_URL/resources?$filter=StatusId ne 1
  • YOUR_MANAGEMENT_API_URL/users?$top=4&$filter=endswith(LastName,'k')&$orderby=LastName
  • YOUR_MANAGEMENT_API_URL/spaces?$orderby=Name desc&$top=3&$filter=substringof('Floor',Name)

Próximas etapas

Para aprender sobre alguns padrões comuns de consulta de API, leia Como consultar as APIs de Gêmeos Digitais do Azure para tarefas comuns.

Para saber mais sobre seus pontos de extremidade de API, leia Como usar o Swagger dos Gêmeos Digitais.

Para examinar a sintaxe OData e os operadores de comparação disponíveis, leia os operadores de comparação OData em Azure Cognitive Search.