Egress e pontos de extremidade nos Gêmeos Digitais do Azure

Artigo
01/21/2020

Importante

Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz dos recursos expandidos 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.

Os pontos de extremidade dos Gêmeos Digitais do Azure representam um agente de mensagens ou eventos na assinatura de um usuário do Azure. Eventos e mensagens podem ser enviados para os tópicos Hubs de Eventos do Azure, Grade de Eventos do Azure e Barramento de Serviço do Azure.

Eventos são roteados para pontos de extremidade de acordo com as preferências de roteamentos predefinidos. Os usuários especificam quais tipos de evento cada ponto de extremidade pode receber.

Para saber mais sobre eventos, roteamento e tipos de eventos, consulte Roteamento de eventos e as mensagens nos Gêmeos Digitais do Azure.

Eventos

Eventos são enviados por objetos de IoT (por exemplo, dispositivos e sensores) para processamento por agentes de mensagens e eventos do Azure. Eventos são definidos pela seguinte Referência de esquema de evento da Grade de Eventos do Azure.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "subject": "ExtendedPropertyKey",
  "data": {
    "SpacesToNotify": [
      "3a16d146-ca39-49ee-b803-17a18a12ba36"
    ],
    "Id": "00000000-0000-0000-0000-000000000000",
      "Type": "ExtendedPropertyKey",
    "AccessType": "Create"
  },
  "eventType": "TopologyOperation",
  "eventTime": "2018-04-17T17:41:54.9400177Z",
  "dataVersion": "1",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

Atributo	Type	Descrição
id	string	Identificador exclusivo do evento.
subject	string	Caminho definido pelo publicador para o assunto do evento.
data	objeto	Dados do evento específicos ao provedor de recursos.
eventType	string	Um dos tipos de evento registrados para a origem do evento.
eventTime	string	A hora em que o evento é gerado com base na hora UTC do provedor.
dataVersion	string	A versão do esquema do objeto de dados. O publicador define a versão do esquema.
metadataVersion	string	A versão do esquema dos metadados do evento. Grade de Eventos define o esquema de propriedades de nível superior. A Grade de Eventos fornece esse valor.
topic	string	Caminho de recurso completo para a origem do evento. Este campo não é gravável. Grade de Eventos fornece esse valor.

Para obter mais informações sobre o esquema de evento da Grade de Eventos:

Examine a Referência de esquema de evento de Grade de Eventos do Azure.
Leia a Referência do Azure EventGrid Node.js SDK EventGridEvent.

Tipos de evento

Os tipos de eventos classificam a natureza do evento e são definidos no campo eventType. Tipos de evento disponíveis são fornecidos pela lista a seguir:

TopologyOperation
UdfCustom
SensorChange
SpaceChange
DeviceMessage

Formatos de eventos para cada um dos tipos de eventos são descritos nas seções a seguir.

TopologyOperation

TopologyOperation aplica-se a alterações no gráfico. O assunto propriedade especifica o tipo de objeto afetado. Os seguintes tipos de objetos podem acionar este evento:

Dispositivo
DeviceBlobMetadata
DeviceExtendedProperty
ExtendedPropertyKey
ExtendedType
KeyStore
Relatório
RoleDefinition
Sensor
SensorBlobMetadata
SensorExtendedProperty
Space
SpaceBlobMetadata
SpaceExtendedProperty
SpaceResource
SpaceRoleAssignment
Sistema
Usuário
UserBlobMetadata
UserExtendedProperty

Exemplo

{
  "id": "00000000-0000-0000-0000-000000000000",
  "subject": "ExtendedPropertyKey",
  "data": {
    "SpacesToNotify": [
      "3a16d146-ca39-49ee-b803-17a18a12ba36"
    ],
    "Id": "00000000-0000-0000-0000-000000000000",
      "Type": "ExtendedPropertyKey",
    "AccessType": "Create"
  },
  "eventType": "TopologyOperation",
  "eventTime": "2018-04-17T17:41:54.9400177Z",
  "dataVersion": "1",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

Valor	Substitua por
YOUR_TOPIC_NAME	O nome do seu tópico personalizado

UdfCustom

UdfCustom é um evento enviado por uma função definida pelo usuário (UDF).

Importante

Este evento deve ser explicitamente enviado do próprio UDF.

Exemplo

{
  "id": "568fd394-380b-46fa-925a-ebb96f658cce",
  "subject": "UdfCustom",
  "data": {
    "TopologyObjectId": "7c799bfc-1bff-4b9e-b15a-669933969d20",
    "ResourceType": "Space",
    "Payload": "\"Room is not available or air quality is poor\"",
    "CorrelationId": "568fd394-380b-46fa-925a-ebb96f658cce"
  },
  "eventType": "UdfCustom",
  "eventTime": "2018-10-02T06:50:15.198Z",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

Valor	Substitua por
YOUR_TOPIC_NAME	O nome do seu tópico personalizado

SensorChange

SensorChange é uma atualização do estado de um sensor com base nas alterações de telemetria.

Exemplo

{
  "id": "60bf5336-2929-45b4-bb4c-b45699dfe95f",
  "subject": "SensorChange",
  "data": {
    "Type": "Classic",
    "DataType": "Motion",
    "Id": "60bf5336-2929-45b4-bb4c-b45699dfe95f",
    "Value": "False",
    "PreviousValue": "True",
    "EventTimestamp": "2018-04-17T17:46:15.4964262Z",
    "MessageType": "sensor",
    "Properties": {
      "ms-client-request-id": "c9e576b7-5eea-4f61-8617-92a57add5179",
      "ms-activity-id": "ct22YwXEGJ5u.605.0"
    }
  },
  "eventType": "SensorChange",
  "eventTime": "2018-04-17T17:46:18.5452993Z",
  "dataVersion": "1",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

Valor	Substitua por
YOUR_TOPIC_NAME	O nome do seu tópico personalizado

SpaceChange

SpaceChange é uma atualização para o estado de um espaço com base nas alterações de telemetria.

Exemplo

{
  "id": "42522e10-b1aa-42ff-a5e7-7181788ffc4b",
  "subject": "SpaceChange",
  "data": {
    "Type": null,
    "DataType": "AvailableAndFresh",
    "Id": "7c799bfc-1bff-4b9e-b15a-669933969d20",
    "Value": "Room is not available or air quality is poor",
    "PreviousValue": null,
    "RawData": null,
    "transactionId": null,
    "EventTimestamp": null,
    "MessageType": null,
    "Properties": null,
    "CorrelationId": "42522e10-b1aa-42ff-a5e7-7181788ffc4b"
  },
  "eventType": "SpaceChange",
  "eventTime": "2018-10-02T06:50:20.128Z",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

Valor	Substitua por
YOUR_TOPIC_NAME	O nome do seu tópico personalizado

DeviceMessage

Ao usar DeviceMessage, você pode especificar uma conexão EventHub para a qual os eventos de telemetria brutos também podem ser roteados a partir do Gêmeos Digitais do Azure.

Observação

DeviceMessage é combinável apenas com EventHub. Você não pode combinar DeviceMessage com nenhum outro tipo de evento.
Você pode especificar apenas um ponto de extremidade da combinação de tipo EventHub ou DeviceMessage.

Configurar pontos de extremidade

O gerenciamento de terminal é exercido por meio da API do Endpoints.

Nos exemplos a seguir, YOUR_MANAGEMENT_API_URL refere-se ao URI de APIs de Gêmeos Digitais:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Nome	Substitua por
NOME_DA_SUA_INSTÂNCIA	O nome da sua instância de Gêmeos Digitais do Azure
SUA_LOCALIZAÇÃO	A região em que sua instância está hospedada

Os exemplos a seguir demonstram como configurar os pontos de extremidade suportados.

Importante

Preste muita atenção ao atributo eventTypes. Ele define quais tipos de evento são manipulados pelo ponto de extremidade e assim, determinam seu roteamento.

Uma solicitação HTTP POST autenticada em relação a:

YOUR_MANAGEMENT_API_URL/endpoints

Rotear para os tipos de evento do Barramento de Serviço do Microsoft Azure SensorChange, SpaceChange e TopologyOperation:

{
  "type": "ServiceBus",
  "eventTypes": [
    "SensorChange",
    "SpaceChange",
    "TopologyOperation"
  ],
  "connectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_PRIMARY_KEY",
  "secondaryConnectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_SECONDARY_KEY",
  "path": "YOUR_TOPIC_NAME"
}

Valor	Substitua por
YOUR_NAMESPACE	O namespace do seu ponto de extremidade
YOUR_PRIMARY_KEY	A cadeia de conexão primária usada para autenticar
YOUR_SECONDARY_KEY	A cadeia de conexão secundária usada para autenticar
YOUR_TOPIC_NAME	O nome do seu tópico personalizado

Rotear para os tipos de eventos da Grade de Eventos do Azure SensorChange, SpaceChange e TopologyOperation:

{
  "type": "EventGrid",
  "eventTypes": [
    "SensorChange",
    "SpaceChange",
    "TopologyOperation"
  ],
  "connectionString": "YOUR_PRIMARY_KEY",
  "secondaryConnectionString": "YOUR_SECONDARY_KEY",
  "path": "YOUR_TOPIC_NAME.westus-1.eventgrid.azure.net"
}

Valor	Substitua por
YOUR_PRIMARY_KEY	A cadeia de conexão primária usada para autenticar
YOUR_SECONDARY_KEY	A cadeia de conexão secundária usada para autenticar
YOUR_TOPIC_NAME	O nome do seu tópico personalizado

Rota para tipos de eventos de Hubs de Eventos do Azure SensorChange, SpaceChange, e TopologyOperation:

{
  "type": "EventHub",
  "eventTypes": [
    "SensorChange",
    "SpaceChange",
    "TopologyOperation"
  ],
  "connectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_PRIMARY_KEY",
  "secondaryConnectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_SECONDARY_KEY",
  "path": "YOUR_EVENT_HUB_NAME"
}

Valor	Substitua por
YOUR_NAMESPACE	O namespace do seu ponto de extremidade
YOUR_PRIMARY_KEY	A cadeia de conexão primária usada para autenticar
YOUR_SECONDARY_KEY	A cadeia de conexão secundária usada para autenticar
YOUR_EVENT_HUB_NAME	O nome do hub de eventos

Rotear para o tipo de evento Hubs de Eventos DeviceMessage. A inclusão de EntityPathconnectionString é obrigatória:

{
  "type": "EventHub",
  "eventTypes": [
    "DeviceMessage"
  ],
  "connectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_PRIMARY_KEY;EntityPath=YOUR_EVENT_HUB_NAME",
  "secondaryConnectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_SECONDARY_KEY;EntityPath=YOUR_EVENT_HUB_NAME",
  "path": "YOUR_EVENT_HUB_NAME"
}

Valor	Substitua por
YOUR_NAMESPACE	O namespace do seu ponto de extremidade
YOUR_PRIMARY_KEY	A cadeia de conexão primária usada para autenticar
YOUR_SECONDARY_KEY	A cadeia de conexão secundária usada para autenticar
YOUR_EVENT_HUB_NAME	O nome do hub de eventos

Observação

Após a criação de um novo endpoint, pode levar de 5 a 10 minutos para começar a receber eventos no endpoint.

Chaves de conexão primária e secundária

Quando uma chave de conexão primária se torna não autorizada, o sistema tenta automaticamente a chave de conexão secundária. Isso fornece um backup e permite a possibilidade de autenticar e atualizar a chave primária através da API do Endpoints.

Se ambas as chaves de conexão primária e secundária não forem autorizadas, o sistema entrará em um tempo de espera de recuo exponencial de até 30 minutos. Os eventos são descartados em cada tempo de espera de recuo acionado.

Sempre que o sistema estiver em um estado de espera de retrocesso, a atualização das chaves de conexões por meio da API do Endpoints pode levar até 30 minutos para entrar em vigor.

Pontos de extremidade inacessíveis

Quando um endpoint se torna inacessível, o sistema entra em um tempo de espera de recuo exponencial de até 30 minutos. Os eventos são descartados em cada tempo de espera de recuo acionado.

Próximas etapas

Aprenda como usar o Swagger de Gêmeos Digitais do Azure.
Saiba mais sobre roteamento de eventos e mensagens em Gêmeos Digitais do Azure.

Compartilhar via

Egress e pontos de extremidade nos Gêmeos Digitais do Azure

Eventos

Tipos de evento

TopologyOperation

Exemplo

UdfCustom

Exemplo

SensorChange

Exemplo

SpaceChange

Exemplo

DeviceMessage

Configurar pontos de extremidade

Chaves de conexão primária e secundária

Pontos de extremidade inacessíveis

Próximas etapas

Recursos adicionais