Fluxo de integração de parceiros de sensores
Esse documento fala sobre as etapas de integração que um parceiro precisa realizar para se integrar ao Gerenciador de Dados do Azure para Agricultura. Ele apresenta uma visão geral das APIs usadas para criar modelos e sensores de lista, formato de telemetria para enviar os dados e, finalmente, a ingestão de dados baseada em IOTHub.
Integração
A integração abrange as etapas exigidas por clientes e parceiros para integração com o Gerenciador de Dados do Azure para Agricultura e começar a receber/enviar telemetria de sensores, respectivamente.
Na figura acima, os blocos destacados em branco são as etapas realizadas por um parceiro, e os destacados em preto são realizados pelos clientes.
Fluxo de parceiros: Fase 1
Aqui está o conjunto de etapas que um parceiro precisa seguir para se integrar ao Gerenciador de Dados do Azure para Agricultura. Essa é uma integração única. No final da fase 1, os parceiros estabelecem a sua identidade no Gerenciador de Dados do Azure para Agricultura.
Criação de aplicativo
Os parceiros precisam ser autenticados e autorizados para acessar as APIs do plano de dados dos clientes do Gerenciador de Dados do Azure para Agricultura. O acesso a essas APIs permite que os parceiros criem modelos de sensores, sensores e objetos de dispositivos na instância do Gerenciador de Dados do Azure para Agricultura dos clientes. As informações do objeto sensor (criadas pelo parceiro) são as utilizadas pelo Gerenciador de Dados do Azure para Agricultura para criar os respectivos dispositivos (sensores) no IOTHub.
Portanto, para ativar a autenticação e autorização, os parceiros precisam fazer o seguinte
- Crie uma conta do Azure (se ainda não tiver uma criada.)
- Criar um aplicativo Microsoft Entra multilocatário – O aplicativo Microsoft Entra multilocatário, como o nome indica, tem acesso a vários locatários de clientes, se os clientes tiverem dado consentimento explícito ao aplicativo parceiro (explicado na etapa de atribuição de função).
Os parceiros podem acessar as APIs no locatário do cliente usando o aplicativo Microsoft Entra multilocatário, registrado no Microsoft Entra ID. O registo da aplicação é feito no portal do Azure para que a plataforma de identidades da Microsoft possa fornecer serviços de autenticação e autorização para a sua aplicação que, por sua vez, acede ao Gerenciador de Dados do Azure para Agricultura.
Siga as etapas fornecidas em Registro do Aplicativo até a Etapa 8 para gerar as seguintes informações:
- ID do Aplicativo (cliente)
- ID do diretório (locatário)
- Nome do aplicativo
Copie e armazene todos os três valores conforme necessário para gerar o token de acesso.
A ID do aplicativo (cliente) criada é como a ID de usuário do aplicativo. Agora, crie a senha correspondente do aplicativo (segredo do cliente) para que o aplicativo se identifique.
Siga as etapas fornecidas em Adicionar um segredo do cliente para gerar o Segredo do cliente e copiá-lo.
Registro
Depois que o parceiro tiver criado com êxito um aplicativo Microsoft Entra multilocatário, os parceiros compartilharão manualmente o ID do APP e o ID do parceiro com a equipe do Gerenciador de Dados do Azure para Agricultura criando um tíquete de suporte. Usando essas informações, o Gerenciador de Dados do Azure para Agricultura valida se é um parceiro autêntico e cria uma identidade de parceiro (sensorPartnerId) usando as APIs internas. Como parte do processo de registro, os parceiros podem usar seu ID de parceiro (sensorPartnerId) ao criar o objeto de sensor/dispositivos e também como parte dos dados do sensor que eles enviam.
A obtenção do ID do parceiro marca a conclusão da integração do parceiro-Gerenciador de Dados do Azure para Agricultura. Agora, o parceiro aguarda a entrada de qualquer um dos seus clientes de sensores para iniciar a ingestão de dados no Gerenciador de Dados do Azure para Agricultura.
Fluxo de cliente
Os clientes que usam o Gerenciador de Dados do Azure para Agricultura estarão cientes de todos os parceiros de sensores suportados e seus respectivos APP IDs. Essa informação está disponível na documentação pública para todos os nossos clientes. Com base nos sensores que os clientes usam e no ID do APP do respectivo parceiro de sensor, o cliente deve fornecer acesso ao parceiro (ID do APP) para começar a enviar os dados do sensor para a instância do Gerenciador de Dados do Azure para Agricultura. Aqui estão as etapas necessárias:
Atribuição de função
Os clientes que optarem por integrar um parceiro específico deverão ter o ID do aplicativo desse parceiro específico. Usando o ID do aplicativo, o cliente precisa fazer o seguinte em sequência.
Consentimento – Como o aplicativo do parceiro reside em um locatário diferente e o cliente deseja que o parceiro acesse determinadas APIs em sua instância do Gerenciador de Dados do Azure para Agricultura, os clientes são obrigados a ligar para um ponto de extremidade específico
https://login.microsoft.com/common/adminconsent/clientId=[client_id]e substituir o [client_id] pelo do parceiro ID do aplicativo. Isso permite que o Microsoft Entra ID dos clientes reconheça esse ID do APP sempre que ele for usado para atribuição de função.Gerenciamento de acesso de identidade (IAM) – Como parte do gerenciamento de acesso de identidade, os clientes criam uma nova atribuição de função para o ID do aplicativo acima, que recebeu consentimento. O Gerenciador de Dados do Azure para Agricultura cria uma nova função chamada Sensor Partner (além das funções existentes de Administrador, Colaborador e Leitor). Os clientes escolhem a função de parceiro do sensor e adicionam o ID do aplicativo parceiro e fornecem acesso.
Iniciação
O cliente informou ao Gerenciador de Dados do Azure para Agricultura que ele precisa obter dados de sensores de um parceiro específico. No entanto, o parceiro ainda não sabe para qual cliente deve enviar os dados do sensor. Portanto, como próxima etapa, o cliente chamaria a API de integração no Gerenciador de Dados do Azure para Agricultura para gerar um link de integração. Após adquirir o link de integração, os clientes compartilhariam as informações abaixo em sequência, compartilhando manualmente ou usando o portal do parceiro.
Link de consentimento e ID do locatário – nessa etapa, o cliente fornece um link de consentimento e ID do locatário. O link de integração se parece com o mostrado no exemplo:
fb-resource-name.farmbeats.com/sensor-partners/partnerId/integrations/IntegrationId/:check-consent?key=jgtHTFGDR?api-version=2021-07-31-previewAlém do link de consentimento, os clientes também forneceriam um ID de locatário. O ID do locatário é usado para buscar o token de acesso necessário para chamar o ponto de extremidade da API do cliente.
Os parceiros validam o link de consentimento fazendo uma chamada GET na API do link de verificação de consentimento. Como o link está totalmente pré-preenchido, solicite o URI conforme esperado pelo Gerenciador de Dados do Azure para Agricultura. Como parte da chamada GET, os parceiros verificam se um código de resposta 200 OK e um IntegrationId devem ser transmitidos na resposta.
Assim que a resposta válida for recebida, os parceiros deverão armazenar dois conjuntos de informações
- Ponto de extremidade da API (pode ser extraído da primeira parte do link de integração)
- IntegrationId (é retornado como parte da resposta à chamada GET)
Depois que o parceiro valida e armazena esses pontos de dados, ele pode permitir que os clientes adicionem sensores cujos dados devem ser enviados para o Gerenciador de Dados do Azure para Agricultura.
Adicionar sensores/dispositivos – Agora, o parceiro sabe para qual cliente (ponto de extremidade da API) ele precisa se integrar, no entanto, ele ainda não sabe para quais sensores ele precisa para enviar os dados. Consequentemente, os parceiros coletam as informações do sensor/dispositivo para os quais os dados precisam ser enviados. Esses dados podem ser coletados manualmente ou por meio da interface do usuário do portal.
Após a adição dos sensores/dispositivos, o cliente pode esperar o fluxo de dados dos respectivos sensores em sua instância do Gerenciador de Dados do Azure para Agricultura. Essa etapa marca a conclusão da integração do cliente para buscar dados do sensor.
Fluxo de parceiros: Fase 2
O parceiro agora tem as informações para chamar um ponto de extremidade de API específico (plano de dados dos clientes), mas ainda não tem as informações sobre onde precisa enviar os dados de telemetria do sensor?
Integração
Como parte da integração, os parceiros precisam usar seu próprio ID de aplicativo, segredo de aplicativo e ID de locatário do cliente adquirido durante a etapa de registro do aplicativo, para gerar um token de acesso usando a API oAuth da Microsoft. Aqui está o comando curl para gerar o token de acesso
curl --location --request GET 'https://login.microsoftonline.com/<customer’s tenant ID> /oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_secret=<Your app secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<Your app ID>' \
--data-urlencode 'scope=https://farmbeats.azure.net/.default'
A resposta deve ser semelhante a:
{
"token_type": "Bearer",
"expires_in": "3599",
"ext_expires_in": "3599",
"expires_on": "1622530779",
"not_before": "1622526879",
"resource": "https://farmbeats.azure.net",
"access_token": "eyJ0eXAiOiJKV1QiLC......tpZCI6InZhcF9"
}
Com o access_token gerado, os parceiros chamam o ponto de extremidade do plano de dados dos clientes para criar modelo de sensor, sensor e dispositivo. Ele é criado nessa instância específica do Gerenciador de Dados do Azure para Agricultura usando as APIs criadas pelo Data Manager for Agriculture. Para obter mais informações sobre APIs de parceiros, consulte a documentação da API de parceiros.
Como parte da API de criação de sensor, os parceiros fornecem o ID do sensor. Depois que o recurso do sensor é criado, os parceiros chamam a API de cadeia de conexão para obter uma cadeia de conexão para esse sensor.
Enviar dados por push
Crie integração de parceiros de sensores
Crie integração de parceiros de sensores para conectar uma parte específica a um fornecedor específico. O IntegrationId é usado posteriormente na criação do sensor. Documentação da API: Integrações de sensores com parceiros - Criar ou atualizar
Criar modelo de dados do sensor
Use o modelo de dados do sensor para definir o modelo de telemetria que está sendo enviado. Toda a telemetria enviada pelo sensor é validada conforme este modelo de dados.
Documentação da API: Modelos de dados de sensores - Criar ou atualizar
Exemplo de telemetria
{
"pressure": 30.45,
"temperature": 28,
"name": "sensor-1"
}
Modelo de dados do sensor correspondente
{
"type": "Sensor",
"manufacturer": "Some sensor manufacturer",
"productCode": "soil m",
"measures": {
"pressure": {
"description": "measures soil moisture",
"dataType": "Double",
"type": "sm",
"unit": "Bar",
"properties": {
"abc": "def",
"elevation": 5
}
},
"temperature": {
"description": "measures soil temperature",
"dataType": "Long",
"type": "sm",
"unit": "Celsius",
"properties": {
"abc": "def",
"elevation": 5
}
},
"name": {
"description": "Sensor name",
"dataType": "String",
"type": "sm",
"unit": "none",
"properties": {
"abc": "def",
"elevation": 5
}
}
},
"sensorPartnerId": "sensor-partner-1",
"id": "sdm124",
"status": "new",
"createdDateTime": "2022-01-24T06:12:15Z",
"modifiedDateTime": "2022-01-24T06:12:15Z",
"eTag": "040158a0-0000-0700-0000-61ee433f0000",
"name": "my sdm for soil moisture",
"description": "description goes here",
"properties": {
"key1": "value1",
"key2": 123.45
}
}
Criar sensor
Crie o sensor usando o ID de integração correspondente e o ID do modelo de dados do sensor. DeviceId e HardwareId são parâmetros opcionais, se necessário, você pode usar o Dispositivos - Criar ou Atualizar para criar o dispositivo.
Documentação da API: Sensores - Criar ou atualizar
Obtenha a cadeia de conexão do IoTHub
Obtenha a cadeia de ligação do IoTHub para enviar a telemetria do sensor para a plataforma do Sensor criado.
Documentação da API: Sensores - Obter cadeia de conexão de conexão
Enviar dados usando Hub IoT do Azure
Use SDKs de dispositivos Hub IoT do Azure para enviar a telemetria usando a cadeia de conexão.
Para todos os eventos de telemetria do sensor, o "timestamp" é uma propriedade obrigatória e deve estar no formato ISO 8601 (AAAA-MM-DDTHH:MM:SSZ).
O parceiro agora está pronto para começar a enviar dados de sensores para todos os sensores usando a respectiva cadeia de conexão fornecida para cada sensor. No entanto, o parceiro enviaria os dados do sensor em formato JSON conforme definido pela FarmBeats. Consulte o esquema de telemetria fornecido aqui.
{
"timestamp": "2022-02-11T03:15:00Z",
"bar": 30.181,
"bar_absolute": 29.748,
"bar_trend": 0,
"et_day": 0.081,
"humidity": 55,
"rain_15_min": 0,
"rain_60_min": 0,
"rain_24_hr": 0,
"rain_day": 0,
"rain_rate": 0,
"rain_storm": 0,
"solar_rad": 0,
"temp_out": 58.8,
"uv_index": 0,
"wind_dir": 131,
"wind_dir_of_gust_10_min": 134,
"wind_gust_10_min": 0,
"wind_speed": 0,
"wind_speed_2_min": 0,
"wind_speed_10_min": 0
}
Depois que os dados forem enviados para o IOTHub, os clientes poderão consultar os dados do sensor usando a API de saída.
Próximas etapas
- Teste nossas APIs aqui.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de