Share via

Fluxo de integração de parceiros de sensores

  • Artigo

Este documento fala sobre as etapas de integração que um parceiro precisa seguir para se integrar ao Data Manager for Agriculture. Ele apresenta uma visão geral das APIs usadas para criar modelos e sensor 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 ambos os clientes e parceiros para integrar com o Data Manager for Agriculture e começar a receber/enviar telemetria de sensor, respectivamente.

Screenshot showing sensor partners flow.

A partir da figura acima, os blocos destacados em branco são os passos dados por um parceiro, e os destacados em preto são feitos pelos clientes.

Fluxo de parceiros: Fase 1

Aqui está o conjunto de etapas que um parceiro precisa fazer para se integrar ao Data Manager for Agriculture. Esta é uma integração única. No final da fase 1, os parceiros estabelecem a sua identidade no Data Manager for Agriculture.

Criação de aplicações

Os parceiros precisam ser autenticados e autorizados a acessar as APIs do plano de dados dos clientes do Data Manager for Agriculture. O acesso a essas APIs permite que os parceiros criem modelos de sensores, sensores ou objetos de dispositivo dentro da instância do Data Manager for Agriculture dos clientes. A informação do objeto sensor (criado pelo parceiro) é o que é usado pelo Data Manager for Agriculture para criar os respetivos dispositivos (sensores) no IOTHub.

Portanto, para habilitar a autenticação e a autorização, os parceiros precisam fazer o seguinte

  1. Crie uma conta do Azure (se você não tiver uma já criada.)
  2. Criar um aplicativo Microsoft Entra multilocatário - O aplicativo Microsoft Entra multilocatário, como o nome significa, tem acesso aos locatários de vários 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 multilocatário Microsoft Entra, registrado no Microsoft Entra ID. O registro do aplicativo é feito no portal do Azure para que a plataforma de identidade da Microsoft possa fornecer serviços de autenticação e autorização para seu aplicativo que, por sua vez, acessa o Data Manager for Agriculture.

Siga os passos fornecidos no Registo da Aplicação até ao Passo8 para gerar as seguintes informações:

  1. ID do aplicativo (cliente)
  2. ID do diretório (locatário)
  3. Nome da Aplicação

Copie e armazene os três valores como você precisaria deles para gerar o token de acesso.

O ID do aplicativo (cliente) criado é como o ID de usuário do aplicativo, e agora você precisa criar sua senha de aplicativo correspondente (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 copie o segredo do cliente gerado.

Registo

Depois que o parceiro cria um aplicativo Microsoft Entra multilocatário com êxito, os parceiros compartilham manualmente a ID do APP e a ID do parceiro com o Data Manager for Agriculture enviando um alias por madma@microsoft.com e-mail. Usando essas informações, o Data Manager for Agriculture 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 sensor/dispositivos e também como parte dos dados do sensor que enviam.

A obtenção do ID do parceiro marca a conclusão da integração do Partner Data Manager for Agriculture. Agora, o parceiro aguarda a entrada de qualquer um de seus clientes de sensores para iniciar sua ingestão de dados no Data Manager for Agriculture.

Fluxo de clientes

Os clientes que usam o Data Manager for Agriculture estarão cientes de todos os parceiros de sensores suportados e seus respetivos IDs de APP. Esta 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 APP ID do seu respetivo parceiro de sensores, o cliente tem de fornecer acesso ao parceiro (APP ID) para começar a enviar os dados do sensor para a instância do Data Manager for Agriculture. Aqui estão os passos necessários:

Atribuição de função

Os clientes que optarem por integrar um parceiro específico devem ter o ID do aplicativo desse parceiro específico. Usando o ID do aplicativo, o cliente precisa fazer as seguintes coisas em sequência.

  1. 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 Data Manager for Agriculture, os clientes precisam chamar um ponto de extremidade https://login.microsoft.com/common/adminconsent/clientId=[client_id] específico e substituir o [client_id] pelo ID do aplicativo dos parceiros. Isso permite que a ID do Microsoft Entra dos clientes reconheça essa ID de APP sempre que a usarem para atribuição de função.

  2. 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 para Agricultura cria uma nova função chamada Parceiro de Sensor (além das funções de Administrador, Colaborador e Leitor existentes). Os clientes escolhem a função de parceiro do sensor e adicionam o ID do aplicativo de parceiro e fornecem acesso.

Início

O cliente conscientizou o Data Manager for Agriculture de que 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. Assim, como próximo passo, o cliente chamaria a API de integração dentro do Data Manager for Agriculture para gerar um link de integração. Após a aquisição do link de integração, os clientes estariam compartilhando as informações abaixo em sequência, compartilhando manualmente ou usando o portal do parceiro.

  1. Link de consentimento & ID do locatário – Nesta etapa, o cliente fornece um link de consentimento & ID do locatário. O link de integração é mostrado no exemplo:

    fb-resource-name.farmbeats.com/sensor-partners/partnerId/integrations/IntegrationId/:check-consent?key=jgtHTFGDR?api-version=2021-07-31-preview

    Alé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 de link de consentimento de verificação. Como o link está totalmente pré-preenchido, solicite o URI conforme esperado pelo Data Manager for Agriculture. Como parte da chamada GET, os parceiros verificam se há um código de resposta 200 OK e IntegrationId a ser passado na resposta.

    Uma vez recebida a resposta válida, os parceiros têm de 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)

    Uma vez que o parceiro valida e armazena esses pontos de dados, eles podem permitir que os clientes adicionem sensores para os quais os dados precisam ser enviados para o Data Manager for Agriculture.

  2. Adicionar sensores/dispositivos – Agora, o parceiro sabe com qual cliente (endpoint de API) precisa se integrar, no entanto, ainda não sabe para quais sensores precisa enviar os dados. Assim, os parceiros coletam as informações do sensor/dispositivo para as 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 respetivos sensores para sua instância Data Manager for Agriculture. Esta 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 sua própria ID de aplicativo, segredo do aplicativo ou 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 o modelo do sensor, o sensor e o dispositivo. Ele é criado nessa instância específica do Data Manager for Agriculture 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 parceiro.

Como parte da API de criação do sensor, os parceiros fornecem o ID do sensor, uma vez que o recurso do sensor é criado, os parceiros chamam a API get connection string para obter uma cadeia de conexão para esse sensor.

Enviar dados por push

Criar integração de parceiros de sensores

Crie a integração de parceiros de sensores para conectar uma parte específica a um provedor específico. O integrationId é usado posteriormente na criação de sensores. Documentação da API: Integrações de parceiros de sensor - 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 de acordo com este modelo de dados.

Documentação da API: Modelos de dados do sensor - Criar ou atualizar

Telemetria de amostra

{
	"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 um 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 Devices - Create Or Update para criar o dispositivo.

Documentação da API: Sensores - Criar ou atualizar

Obter cadeia de conexão IoTHub

Obtenha a cadeia de conexão IoTHub para enviar a telemetria do sensor para a plataforma do Sensor criado.

Documentação da API: Sensores - Obter cadeia de conexão

Enviar dados por push usando o Hub IoT

Use SDKs de dispositivo do Hub IoT para enviar por push a telemetria usando a cadeia de conexão.

Para todos os eventos de telemetria do sensor, "timestamp" é uma propriedade obrigatória e deve estar no formato ISO 8601 (AAAA-MM-DDTHH:MM:SSZ).

O parceiro está agora pronto para começar a enviar dados do sensor para todos os sensores usando a respetiva cadeia de conexão fornecida para cada sensor. No entanto, o parceiro enviaria os dados do sensor em um formato JSON, conforme definido pelo 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
}

Uma vez que os dados são enviados para IOTHub, os clientes poderão consultar os dados do sensor usando a API de saída.

Próximos passos

  • Teste as nossas APIs aqui.