センサーパートナー統合フロー

[アーティクル]
05/23/2024

このドキュメントでは、Data Manager for Agriculture との統合のためにパートナーが行う必要があるオンボーディング手順について説明します。モデルとリストセンサーの作成に使用される API、データをプッシュするためのテレメトリ形式、そして最後に IOTHub ベースのデータインジェストの概要について説明します。

オンボード

オンボードでは、Data Manager for Agriculture と統合を行い、センサーテレメトリの受信/送信をそれぞれ開始するために顧客およびパートナーの両方で必要となる手順をカバーします。

センサーパートナーフローを示すスクリーンショット。

上の図から、白で強調表示されているブロックはパートナーが実行する手順であり、黒で強調表示されたブロックは顧客によって行われます。

パートナーフロー: フェーズ 1

Data Manager for Agriculture との統合のためにパートナーが行う必要がある一連の手順を次に示します。これは 1 回限りの統合です。フェーズ 1 の最後で、パートナーは Data Manager for Agriculture で ID を確立します。

アプリの作成

パートナーは、Data Manager for Agriculture 顧客のデータプレーン API にアクセスするために認証され、承認されている必要があります。これらの API へのアクセスによって、パートナーは顧客の Data Manager for Agriculture インスタンス内にセンサーモデル、センサーオブジェクトおよびデバイスオブジェクトを作成できます。 (パートナーによって作成された) センサーオブジェクト情報を、Data Manager for Agriculture が IOTHub でそれぞれのデバイス (センサー) を作成するために使用します。

そのため、認証および認可を有効にするには、パートナーは以下を行う必要があります

Azure アカウントを作成します (まだ作成していない場合)。
マルチテナント Microsoft Entra アプリを作成します - マルチテナントの Microsoft Entra アプリは、その名前が示すとおり、顧客がパートナーアプリに明示的な同意を与えた場合、複数の顧客のテナントにアクセスできます (「ロールの割り当て」の手順で説明)。

パートナーは、Microsoft Entra ID に登録されているマルチテナント Microsoft Entra アプリを使用して、顧客テナントの API にアクセスできます。アプリの登録が Azure portal で行われると、Microsoft ID プラットフォームがアプリケーションに対して認証および承認サービスを提供し、それによりアプリケーションが Data Manager for Agriculture にアクセスできるようになります。

アプリの登録に関する記事に記載されている手順にステップ 8 まで従って、次の情報を生成します。

アプリケーション (クライアント) ID
ディレクトリ (テナント) ID
アプリ名

3 つの値をすべてコピーして保存します。これらは、アクセストークンを生成するために必要になります。

作成されるアプリケーション (クライアント) ID は、アプリケーションのユーザー ID のようなものです。ここで、そのアプリケーションを認証するための対応するアプリケーションパスワード (クライアントシークレット) を作成する必要があります。

「クライアントシークレットを追加する」に記載されている手順に従って、クライアントシークレットを生成し、その生成されたクライアントシークレットをコピーします。

登録

パートナーはマルチテナントの Microsoft Entra アプリを正常に作成したら、サポートチケットを作成することでアプリ ID とパートナー ID を手動で Data Manager for Agriculture チームと共有します。 Data Manager for Agriculture は、この情報を使用して本物のパートナーであるかどうかを検証し、内部 API を使用してパートナー ID (sensorPartnerId) を作成します。登録プロセスの一環として、パートナーは、パートナー ID (sensorPartnerId) を、センサー/デバイスオブジェクトの作成中に使用したり、プッシュするセンサーデータの一部として使用したりできます。

パートナー ID を取得すると、パートナーと Data Manager for Agriculture との統合が完了します。これで、パートナーは、センサー顧客からの入力を待って、Data Manager for Agriculture へのデータインジェストを開始します。

顧客フロー

Data Manager for Agriculture を使用している顧客は、サポートされているすべてのセンサーパートナーとそれぞれのアプリ ID を認識しています。この情報は、全顧客向けのパブリックドキュメントで入手できます。顧客が使用するセンサーとそれぞれのセンサーパートナーのアプリ ID に基づいて、顧客はパートナー (アプリ ID) にアクセスを提供して、センサーデータを Data Manager for Agriculture インスタンスにプッシュし始める必要があります。必要な手順は次のとおりです。

ロール割り当て

特定のパートナーにオンボードすることを選択した顧客は、その特定のパートナーのアプリ ID を持っている必要があります。アプリ ID を使用して顧客は次のことを順に行う必要があります。

同意 – パートナーのアプリは別のテナントに存在し、顧客は自分の Data Manager for Agriculture インスタンス内の特定の API にパートナーがアクセスすることを望んでいるため、顧客は特定のエンドポイント https://login.microsoft.com/common/adminconsent/clientId=[client_id] を呼び出し、[client_id] をパートナーのアプリ ID に置き換える必要があります。これにより、顧客の Microsoft Entra ID は、このアプリ ID を、それをロールの割り当てに使用するたびに認識できます。
ID アクセス管理 (IAM) – ID アクセス管理の一環として、顧客は上記のアプリ ID に新しいロールの割り当てを作成します。この割り当てには同意が提供されています。 Data Manager for Agriculture では、センサーパートナーという新しいロールが作成されます (既存の管理者、共同作成者、閲覧者のロールに加えて)。顧客はセンサーパートナーロールを選択し、パートナーアプリ ID を追加してアクセスを提供します。

開始

顧客は、特定のパートナーからセンサーデータを取得する必要があることを Data Manager for Agriculture に認識させました。ただし、パートナーはどの顧客のためにセンサーデータを送信すべきかをまだ認識していません。そのため、次の手順として、顧客は Data Manager for Agriculture 内で統合 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 呼び出しを行って、同意リンクを検証します。リンクは、Data Manager for Agriculture が予期する通りの完全に事前設定された要求 URI です。 GET 呼び出しの一環として、パートナーは 200 OK 応答コードと IntegrationId が応答で渡されることを確認します。

有効な応答を受信したら、パートナーは 2 セットの情報を保存する必要があります
- API エンドポイント (統合リンクの最初の部分から抽出できます)
- IntegrationId (GET 呼び出しへの応答の一部として返されます)
パートナーは、これらのデータポイントを検証して保存すると、データを Data Manager for Agriculture にプッシュする必要があるセンサーを顧客が追加できるようにします。
センサー/デバイスを追加する – パートナーは、どの顧客 (API エンドポイント) を統合する必要があるかは把握していますが、どのセンサーに対してデータをプッシュすべきかはまだ把握していません。そのため、パートナーは、データをプッシュする必要があるセンサー/デバイスの情報を収集します。このデータは、手動またはポータル UI を使用して収集できます。

センサー/デバイスが追加されると、顧客は、それぞれのセンサーのデータフローが Data Manager for Agriculture インスタンスに送られると期待できます。この手順により、センサーデータをフェッチするための顧客オンボードが完了します。

パートナーフロー: フェーズ 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 では、パートナーは顧客のデータプレーンエンドポイントを呼び出して、センサーモデル、センサー、およびデバイスを作成します。これは、Data Manager for Agriculture によって構築された API を使用して、その特定の Data Manager for Agriculture インスタンス内に作成されます。パートナー 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 Hub を使用してデータをプッシュする

IoT Hub デバイス 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 のテストはここで行います。

次の方法で共有

センサーパートナー統合フロー

オンボード

パートナーフロー: フェーズ 1

アプリの作成

登録

顧客フロー

ロール割り当て

開始

パートナーフロー: フェーズ 2

統合

データのプッシュ

センサーパートナー統合の作成

センサーデータモデルを作成する

センサーを作成する

IoTHub 接続文字列を取得する

IoT Hub を使用してデータをプッシュする

次のステップ

フィードバック

その他のリソース

次の方法で共有

センサー パートナー統合フロー

オンボード

パートナー フロー: フェーズ 1

アプリの作成

登録

顧客フロー

ロール割り当て

開始

パートナー フロー: フェーズ 2

統合

データのプッシュ

センサー パートナー統合の作成

センサー データ モデルを作成する

センサーを作成する

IoTHub 接続文字列を取得する

IoT Hub を使用してデータをプッシュする

次のステップ

フィードバック

その他のリソース

センサーパートナー統合フロー

パートナーフロー: フェーズ 1

パートナーフロー: フェーズ 2

センサーパートナー統合の作成

センサーデータモデルを作成する