顧客としてのセンサー統合

[アーティクル]
11/15/2023

センサーパートナーと統合する手順に従って、パートナーが Data Manager for Agriculture インスタンスへのデータのプッシュを開始できるようにします。

各センサーパートナーには、独自のマルチテナント Microsoft Entra アプリが作成され、Data Manager for Agriculture プラットフォームで公開されています。プラットフォームで既定でサポートされているセンサーパートナーは、Davis Instruments (sensorPartnerId: DavisInstruments) です。

オンボードされているセンサーパートナーの使用を開始するには、センサーパートナーが App Registrations で表示されるように、センサーパートナーに同意する必要があります。次の手順に従います。

"グローバル管理者" または "特権ロール管理者" の資格情報を使用して Azure portal にログインします。
Davis Intruments の場合は、このリンクをクリックして同意してください。
アクセス許可のレビューページで、Microsoft Entra アプリは最小限の "ユーザープロファイルの読み取り" アクセス許可を要求します。このアクセス許可レベルは、Data Manager for Agriculture とのセンサー統合に十分です。
[同意する] ボタンをクリックして、管理者の同意を付与します。
次に、App Registrations ページの [すべてのアプリケーション] タブで Davis Instruments WeatherLink Data Manager for Agriculture Connector を探します (画像では一般的なパートナーを示します)。
アクセス権を付与する特定のパートナーアプリのアプリケーション (クライアント) ID をコピーします。

手順 2: パートナーアプリにロールの割り当てを追加する

次の手順では、Azure portal でロールを割り当てて、センサーパートナーアプリケーションに承認を提供します。 Data Manager for Agriculture では、Azure RBAC を使用して認可要求を管理します。

Azure portal にログインし、Data Manager for Agriculture リソースを作成したリソースグループに移動します。

Note

[リソースグループ] タブに、作成した Data Manager for Agriculture リソースが見つからない場合は、[非表示の型の表示] チェックボックスをオンにします。

次の図に示すように、オプションウィンドウの左側に IAM (Identity Access Management) メニューオプションがあります。

Screenshot showing role assignment.

[追加] > [ロールの割り当ての追加] の順にクリックすると、ポータルの右側にウィンドウが開き増す。ドロップダウンから 3 つのロールのいずれかを選択してください。

AgFood Platform Sensor パートナー共同作成者 - センサーに固有の CRU (作成、読み取り、更新) 操作のすべての特権を持ちます。

ロールの割り当てを完了するには、次の手順を実行します。

前述のロールを選択します。
[アクセスの割り当て先] セクションで、[ユーザー、グループ、サービスプリンシパル] を選択します。
[選択] セクションにセンサーパートナーのアプリ名または ID を貼り付けます (図を参照)。
[保存] をクリックしてロールを割り当てます。

Screenshot showing app selection for authorization.

この手順により、センサーパートナーアプリに Azure Data Manager for Agriculture リソースへのアクセス権が割り当てられたロールに基づいて付与されます。

手順 3: センサー統合を有効にする

呼び出しを開始する前に、センサー統合を有効にする必要があります。この手順では、Data Manager for Agriculture インスタンスでのセンサー統合に必要な内部 Azure リソースをプロビジョニングします。これを行うには、次の armclient コマンドを実行します。

armclient patch /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>?api-version=2021-09-01-preview "{properties:{sensorIntegration:{enabled:'true'}}}"

サンプル出力:

{
  "id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>",
  "type": "Microsoft.AgFoodPlatform/farmBeats",
  "sku": {
    "name": "A0"
  },
  "systemData": {
    "createdBy": "<customer-id>",
    "createdByType": "User",
    "createdAt": "2022-03-11T03:36:32Z",
    "lastModifiedBy": "<customer-id>",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2022-03-11T03:40:06Z"
  },
  "properties": {
    "instanceUri": "https://<farmbeats-instance-name>.farmbeats.azure.net/",
    "provisioningState": "Succeeded",
    "sensorIntegration": {
      "enabled": "True",
      "provisioningState": "**Creating**"
    },
    "publicNetworkAccess": "Enabled"
  },
  "location": "eastus",
  "name": "myfarmbeats"
}

このジョブが完了するまでに数分かかることがあります。ジョブの状態を把握するには、次の armclient コマンドを使用します。

armclient get /subscriptions/<subscription-id>/resourceGroups/<resource-group-name> /providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>?api-version=2021-09-01-preview

完了した状態を確認するには、provisioningState 属性を確認します。前の手順の [作成中] から状態が [成功] に変更されている必要があります。

サンプル出力:

{
  "id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>",
  "type": "Microsoft.AgFoodPlatform/farmBeats",
  "sku": {
    "name": "A0"
  },
  "systemData": {
    "createdBy": "<customer-id>",
    "createdByType": "User",
    "createdAt": "2022-03-11T03:36:32Z",
    "lastModifiedBy": "<customer-id>",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2022-03-11T03:40:06Z"
  },
  "properties": {
    "instanceUri": "https://<customer-host-name>.farmbeats.azure.net/",
    "provisioningState": "Succeeded",
    "sensorIntegration": {
      "enabled": "True",
      "provisioningState": "**Succeeded**"
    },
    "publicNetworkAccess": "Enabled"
  },
  "tags": {
    "usage": "<sensor-partner-id>"
  },
  "location": "eastus",
  "name": "<customer-id>"
}

センサー統合手順が完了したら、センサー統合オブジェクトを作成できるようになります。

手順 4: 統合オブジェクトを作成する

SensorPartnerIntegrations コレクションを使用し、SensorPartnerIntegrations_CreateOrUpdate API を呼び出して、特定のセンサーパートナーの統合オブジェクトを作成します。センサーパートナー (例: Davis) のすべての顧客には、Data Manager for Agriculture リソースで作成された一意の統合 ID が必要です。

評価する必要があるパスは 2 つあります。

センサーパートナーによって提供されるセンサーの所有者である場合は、センサーパートナーのアカウントの統合オブジェクト (ID) を 1 つだけ作成します。
エンドユーザー (つまり、Farmers/Retailers/Agronomists) がセンサーを所有している場合は、各エンドユーザーがセンサーパートナーとの独自のアカウントを持っているため、エンドユーザーごとに一意の統合オブジェクト (ID) を作成します。

API エンドポイント: PATCH /sensor-partners/{sensorPartnerId}/integrations/{integrationID}

同意リンクを要求するセクションは、センサーパートナー統合フローの一部です。この同意リンクは、センサーパートナーが顧客がサービスの有効なユーザーであるかどうかを検証するための方法です。センサーの統合は同意キーに関連付けられています。

センサーパートナーである Davis Instruments は、この UI を使用して、設定を有効にし、同意リンクを要求します。

センサーパートナーは、check-consent API エンドポイントを呼び出して有効性を確認します。同意リンクを生成するには、SensorPartnerIntegrations_GenerateConsentLink API を使用し、手順 (3) から作成した統合 ID を指定する必要があります。応答として、consentLink という文字列を取得します。この文字列をコピーし、センサーパートナーに渡してさらに検証します。 Davis Instruments のセンサーを使用している場合は、このページの指示に従ってください。

API エンドポイント: PATCH /sensor-partners/{sensorPartnerId}/integrations/{integrationId}/: generate-consent-link

この手順では、顧客の視点からセンサーパートナーのオンボーディングを完了したことをマークします。では、API エンドポイントを呼び出してセンサーモデル、デバイスモデル、センサー、デバイスを作成するために必要なすべての情報を取得します。パートナーは、センサー ID ごとに生成された接続文字列を使用してセンサーイベントをプッシュできるようになりました。

最後の手順は、センサーイベントの使用を開始することです。イベントを使用する前に、すべてのセンサー ID を特定のパーティ ID とリソース (フィールド、季節フィールド) にマッピングする必要があります。

手順 6: センサーマッピングを作成する

SensorMappings コレクションを使用し、SensorMappings_CreateOrUpdate API を呼び出して、各センサーのマッピングを作成します。マッピングは、センサー ID を特定の PartyID とリソース (フィールド、季節フィールドなど) に関連付けることに過ぎません。 PartyID とリソースは、Data Manager for Agriculture システムに既に存在します。この関連付けにより、プラットフォームとして、リソースとパーティーディメンションの共通のジオメトリに基づいてデータサイエンスモデルを構築できるようになります。すべてのデータソース (サテライト、天気、ファーム操作) は、パーティーとリソースに関連付けられています。センサーレベルごとにこのマッピングオブジェクトを確立すると、すべての農業ユースケースにおいてセンサーデータのメリットを得られます。

API エンドポイント: PATCH /sensor-mappings/{sensorMappingId}

手順 7: センサーイベントを使用する

SensorEvents コレクションを使用してSensorEvents_List API を呼び出し、センサーによってプッシュされたデータを使用します。次の情報を指定する必要があります。

sensorId (データを表示するセンサーを指定します)
sensorPartnerId (このデータをプッシュしているセンサーパートナーを指定します)
startDateTime & endDateTime (時間範囲フィルターを使用すると、要求されたタイムラインにデータがスライスされます)

API エンドポイント: GET /sensor-events

次のステップ

API のテストはここで行います。

次の方法で共有

顧客としてのセンサー統合

手順 2: パートナーアプリにロールの割り当てを追加する

手順 3: センサー統合を有効にする

手順 4: 統合オブジェクトを作成する

手順 6: センサーマッピングを作成する

手順 7: センサーイベントを使用する

次のステップ

フィードバック

その他のリソース

次の方法で共有

顧客としてのセンサー統合

手順 1: センサー パートナー アプリを特定し、同意する

手順 2: パートナー アプリにロールの割り当てを追加する

手順 3: センサー統合を有効にする

手順 4: 統合オブジェクトを作成する

手順 5: 同意リンクを生成する

手順 6: センサー マッピングを作成する

手順 7: センサー イベントを使用する

次のステップ

フィードバック

その他のリソース

手順 1: センサーパートナーアプリを特定し、同意する

手順 2: パートナーアプリにロールの割り当てを追加する

手順 6: センサーマッピングを作成する

手順 7: センサーイベントを使用する