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

传感器合作伙伴集成流

项目
05/27/2024

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

登记

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

显示传感器合作伙伴流的屏幕截图。

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

合作伙伴流：第 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 应用后，合作伙伴可以通过创建支持工单手动与用于农业的数据管理器团队共享应用 ID 和合作伙伴 ID。用于农业的数据管理器使用此信息验证其是否是真实的合作伙伴，并使用内部 API 创建合作伙伴标识 (sensorPartnerId)。在注册过程中，合作伙伴可以在创建传感器/设备对象时使用其合作伙伴 ID (sensorPartnerId)，也可以将其纳入推送的传感器数据中。

获取合作伙伴 ID 即标志着合作伙伴与用于农业的数据管理器集成完成。现在，合作伙伴等待其任何传感器客户输入数据，以开始将数据引入到用于农业的数据管理器中。

客户流

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

角色分配

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

同意 – 由于合作伙伴的应用位于不同的租户中，并且客户希望合作伙伴访问其用于农业的数据管理器实例中的某些 API，因此客户需要调用特定终结点 https://login.microsoft.com/common/adminconsent/clientId=[client_id] 并将 [client_id] 替换为合作伙伴的应用 ID。这样，客户的 Microsoft Entra ID 才能够在每次使用应用 ID 进行角色分配时识别到它。
标识访问管理 (IAM) – 作为标识访问管理的一部分，客户应为上述已获得同意的应用 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，在创建传感器资源后，合作伙伴会调用获取连接字符串 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。

通过