你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

传感器合作伙伴集成流

项目
10/26/2023

本文档介绍合作伙伴需要采取的加入步骤，以便与农业数据管理器集成。它概述了用于创建模型和列表传感器的 API、用于推送数据的遥测格式，最后介绍基于 IOTHub 的数据引入。

登记

载入涵盖客户和合作伙伴与农业数据管理器集成所需的步骤，并开始分别接收/发送传感器遥测数据。

Screenshot showing sensor partners flow.

从上图中，以白色突出显示的块是合作伙伴执行的步骤，以黑色突出显示的步骤由客户完成。

合作伙伴流：阶段 1

下面是合作伙伴为与农业数据管理器集成而需要执行的步骤集。这是一次性集成。在第 1 阶段结束时，合作伙伴在农业数据管理器中建立其标识。

应用创建

合作伙伴需要经过身份验证和授权才能访问农业客户数据平面 API 的数据管理器。通过访问这些 API，合作伙伴可以在客户的农业数据管理器实例中创建传感器模型、传感器和设备对象。传感器对象信息（由合作伙伴创建）是农业数据管理器用于在 IOTHub 中创建相应设备（传感器）的内容。

因此，若要启用身份验证和授权，合作伙伴需要执行以下操作

创建 Azure 帐户 （如果尚未创建帐户）。
创建多租户 Microsoft Entra 应用 - 多租户 Microsoft Entra 应用作为名称表示，如果客户已明确同意合作伙伴应用（在角色分配步骤中解释），则有权访问多个客户的租户。

合作伙伴可以使用在 Microsoft Entra ID 中注册的多租户 Microsoft Entra 应用访问客户租户中的 API。应用注册在Azure 门户上完成，因此Microsoft 标识平台可以为应用程序提供身份验证和授权服务，进而访问农业数据管理器。

按照应用注册中提供的步骤操作，直到步骤 8 生成以下信息：

应用程序(客户端) ID
目录（租户）ID
应用名称

复制并存储所有三个值，因为你需要它们来生成访问令牌。

创建的应用程序（客户端）ID 类似于应用程序的用户 ID，现在需要创建其相应的应用程序密码（客户端密码），以便应用程序标识自身。

按照添加客户端密码中提供的步骤生成客户端密码并复制生成的客户端密码。

注册

合作伙伴成功创建多租户 Microsoft Entra 应用后，合作伙伴会通过电子邮件别名 madma@microsoft.com 与用于农业的数据管理器手动共享应用 ID 和合作伙伴 ID。使用此用于农业的数据管理器验证它是否为正宗的合作伙伴，并使用内部 API 创建合作伙伴标识（sensorPartnerId）。作为注册过程的一部分，合作伙伴能够在创建传感器/设备对象时使用其合作伙伴 ID（sensorPartnerId），并作为他们推送的传感器数据的一部分。

获取合作伙伴 ID 将标志着用于农业的合作伙伴数据管理器的完成。现在，合作伙伴会等待来自任何传感器客户的输入，以启动其数据引入农业数据管理器。

客户流

使用用于农业的数据管理器的客户将了解所有受支持的传感器合作伙伴及其各自的应用 ID。此信息可在所有客户的公共文档中获取。根据客户使用的传感器及其各自的传感器合作伙伴的应用 ID，客户必须提供对合作伙伴（APP ID）的访问权限，才能开始将传感器数据推送到其农业数据管理器实例。以下是所需的步骤：

角色分配

选择加入特定合作伙伴的客户应具有该特定合作伙伴的应用 ID。使用应用 ID 客户需要按顺序执行以下操作。

同意 – 由于合作伙伴的应用驻留在不同的租户中，客户希望合作伙伴访问其用于农业的数据管理器实例中的某些 API，因此客户需要调用特定终结点 https://login.microsoft.com/common/adminconsent/clientId=[client_id] 并将 [client_id] 替换为合作伙伴的应用 ID。这样，客户 Microsoft Entra ID 就可以在客户将其用于角色分配时识别此应用 ID。
标识访问管理（IAM） - 作为标识访问管理的一部分，客户会向上述应用 ID 创建新的角色分配，该 ID 已提供同意。农业数据管理器创建一个名为传感器合作伙伴的新角色（除了现有的管理员、参与者、读者角色）。客户选择传感器合作伙伴角色，并添加合作伙伴应用 ID 并提供访问权限。

启动

客户已使农业数据管理器知道他们需要从特定合作伙伴获取传感器数据。但是，合作伙伴尚不知道应向哪个客户发送传感器数据。因此，下一步，客户将调用农业数据管理器中的集成 API 来生成集成链接。获取集成链接后，客户将按顺序共享以下信息，无论是手动共享还是使用合作伙伴的门户。

同意链接和租户 ID – 在此步骤中，客户提供同意链接和租户 ID。集成链接如示例中所示：

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

除了同意链接，客户还会提供租户 ID。租户 ID 用于提取调用客户 API 终结点所需的访问令牌。

合作伙伴通过在检查同意链接 API 上发出 GET 调用来验证同意链接。由于链接完全预填充了农业数据管理器的预期请求 URI。作为 GET 调用的一部分，合作伙伴检查在响应中传递 200 OK 响应代码和 IntegrationId。

收到有效响应后，合作伙伴必须存储两组信息
- API 终结点（可以从集成链接的第一部分提取）
- IntegrationId （作为 GET 调用响应的一部分返回）
合作伙伴验证并存储这些数据点后，客户就可以添加数据必须推送到农业数据管理器的传感器。
添加传感器/设备 - 现在，合作伙伴知道他们需要与哪些客户（API 终结点）集成，但是，他们仍然不知道推送数据所需的所有传感器。因此，合作伙伴收集需要向其推送数据的传感器/设备信息。可以手动或通过门户 UI 收集此数据。

添加传感器/设备后，客户可以期望相应的传感器数据流流入其农业数据管理器实例。此步骤标志着客户载入完成以提取传感器数据。

合作伙伴流：阶段 2

合作伙伴现在有信息来调用特定的 API 终结点（客户的数据平面），但他们仍然没有关于他们需要在哪里推送传感器遥测数据的信息？

集成

作为集成的一部分，合作伙伴需要使用自己的应用 ID、应用机密和客户在应用注册步骤中获取的租户 ID，才能使用 Microsoft 的 oAuth API 生成访问令牌。下面是用于生成访问令牌的 curl 命令

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'

响应应如下所示：

{
  "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"
}

借助生成的access_token，合作伙伴调用客户的数据平面终结点来创建传感器模型、传感器和设备。它使用由农业数据管理器生成的 API 在该特定农业数据管理器实例中创建。有关合作伙伴 API 的详细信息，请参阅合作伙伴 API 文档。

作为传感器创建 API 的一部分，合作伙伴提供传感器 ID，创建传感器资源后，合作伙伴会调用 get 连接字符串 API 以获取该传感器的连接字符串。

推送数据

创建传感器合作伙伴集成

创建传感器合作伙伴集成以将特定参与方与特定提供商连接。 integrationId 稍后用于传感器创建。 API 文档：传感器合作伙伴集成 - 创建或更新

创建传感器数据模型

使用传感器数据模型定义要发送的遥测模型。根据此数据模型验证传感器发送的所有遥测数据。

API 文档：传感器数据模型 - 创建或更新

样本遥测数据

{
	"pressure": 30.45,
	"temperature": 28,
	"name": "sensor-1"
}

相应的传感器数据模型

{
  "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
  }
}

创建传感器

使用相应的集成 ID 和传感器数据模型 ID 创建传感器。 DeviceId 和 HardwareId 是可选参数，如果需要，可以使用设备 - 创建或更新来创建设备。

API 文档：传感器 - 创建或更新

获取 IoTHub 连接字符串

获取 IoTHub 连接字符串，将传感器遥测数据推送到创建的传感器的平台。

API 文档：传感器 - 获取连接字符串

使用 IoT 中心推送数据

使用IoT 中心设备 SDK 通过连接字符串推送遥测数据。

对于所有传感器遥测事件，“timestamp”是必需属性，必须采用 ISO 8601 格式（YYYY-MM-DDTHH：MM：SSZ）。

现在，合作伙伴已全部设置为使用为每个传感器提供的相应连接字符串为所有传感器推送传感器数据。但是，合作伙伴将采用 FarmBeats 定义的 JSON 格式发送传感器数据。请参阅此处提供的遥测架构。

{
	"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
}

将数据推送到 IOTHub 后，客户将能够使用出口 API 查询传感器数据。

后续步骤

在此处测试我们的 API。