다음을 통해 공유

센서 파트너 통합 흐름

  • 아티클

이 문서에서는 파트너가 Data Manager for Agriculture와 통합하기 위해 수행해야 하는 온보딩 단계에 대해 설명합니다. 모델 및 목록 센서를 만드는 데 사용되는 API, 데이터를 푸시하기 위한 원격 분석 형식, 마지막으로 IOTHub 기반 데이터 수집을 간략하게 설명합니다.

온보딩

온보딩은 두 고객 및 파트너가 Data Manager for Agriculture와 통합하고 센서 원격 분석을 각각 받기/보내기 시작하는 데 필요한 단계를 다룹니다.

센서 파트너 흐름을 보여 주는 스크린샷.

위의 그림에서 흰색으로 강조 표시된 블록은 파트너가 수행한 단계이며, 검은색으로 강조 표시된 블록은 고객이 수행합니다.

파트너 흐름: 1단계

다음은 Data Manager for Agriculture와 통합하기 위해 파트너가 수행해야 하는 일련의 단계입니다. 일회성 통합입니다. 1단계가 끝나면 파트너는 Data Manager for Agriculture에서 자신의 ID를 설정합니다.

앱 만들기

파트너는 인증을 받고 Data Manager for Agriculture 고객의 데이터 평면 API에 액세스할 수 있는 권한을 부여해야 합니다. 파트너는 이러한 API에 액세스하여 고객의 Data Manager for Agriculture 인스턴스 내에서 센서 모델, 센서 및 디바이스 개체를 만들 수 있습니다. 파트너가 만든 센서 개체 정보는 Data Manager for Agriculture에서 IOTHub에서 각 디바이스(센서)를 만드는 데 사용됩니다.

따라서 인증 및 권한 부여를 사용하도록 설정하려면 파트너는 다음을 수행해야 합니다.

  1. Azure 계정을 만듭니다(아직 만든 계정이 없는 경우).
  2. 다중 테넌트 Microsoft Entra 앱 만들기 - 이름에서 알 수 있듯이 다중 테넌트 Microsoft Entra 앱은 고객이 파트너 앱에 명시적으로 동의한 경우(역할 할당 단계에서 설명) 여러 고객의 테넌트에 액세스할 수 있습니다.

파트너는 Microsoft Entra ID에 등록된 다중 테넌트 Microsoft Entra 앱을 사용하여 고객 테넌트의 API에 액세스할 수 있습니다. 앱 등록은 Azure Portal 수행되므로 Microsoft ID 플랫폼 애플리케이션에 대한 인증 및 권한 부여 서비스를 제공할 수 있으며, 이 서비스는 Data Manager for Agriculture에 액세스합니다.

앱 등록에 제공된 단계를 8단계까지 수행하여 다음 정보를 생성합니다.

  1. 애플리케이션(클라이언트) ID
  2. 디렉터리(테넌트) ID
  3. 앱 이름

액세스 토큰을 생성하는 데 필요한 세 가지 값을 모두 복사하고 저장합니다.

만든 애플리케이션(클라이언트) ID는 애플리케이션의 사용자 ID와 같으며, 이제 애플리케이션이 자체적으로 식별할 수 있도록 해당 애플리케이션 암호(클라이언트 암호)를 만들어야 합니다.

클라이언트 암호 추가에 제공된 단계에 따라 클라이언트 암호를 생성하고 생성된 클라이언트 암호를 복사합니다.

등록

파트너가 다중 테넌트 Microsoft Entra 앱을 성공적으로 만들면 파트너는 지원 티켓을 만들어 Data Manager for Agriculture 팀과 앱 ID 및 파트너 ID를 수동으로 공유합니다. 이 정보를 사용하여 Data Manager for Agriculture는 진정한 파트너인지 유효성을 검사하고 내부 API를 사용하여 파트너 ID(sensorPartnerId)를 만듭니다. 등록 프로세스의 일부로 파트너는 센서/디바이스 개체를 만드는 동안 파트너 ID(sensorPartnerId)를 사용하고 푸시하는 센서 데이터의 일부로 사용할 수 있습니다.

파트너 ID를 가져오면 파트너와 Data Manager for Agriculture 통합이 완료됩니다. 이제 파트너는 센서 고객의 입력이 Data Manager for Agriculture로 데이터 수집을 시작할 때까지 기다립니다.

고객 흐름

Data Manager for Agriculture를 사용하는 고객은 지원되는 모든 센서 파트너와 해당 APP ID를 알고 있습니다. 이 정보는 모든 고객을 위한 공용 설명서에서 확인할 수 있습니다. 고객이 사용하는 센서 및 해당 센서 파트너의 APP ID에 따라 고객은 파트너(APP ID)에 대한 액세스를 제공하여 센서 데이터를 Data Manager for Agriculture 인스턴스로 푸시하기 시작해야 합니다. 필요한 단계는 다음과 같습니다.

역할 할당

특정 파트너에 온보딩하기로 선택한 고객은 해당 특정 파트너의 앱 ID가 있어야 합니다. 앱 ID를 사용하는 고객은 다음 작업을 순서대로 수행해야 합니다.

  1. 동의 – 파트너의 앱이 다른 테넌트에 있고 고객이 파트너가 자신의 Data Manager for Agriculture instance 특정 API에 액세스하기를 원하기 때문에 고객은 특정 엔드포인트 https://login.microsoft.com/common/adminconsent/clientId=[client_id]를 호출하고 [client_id]를 파트너의 앱 ID로 바꿔야 합니다. 이를 통해 고객용 Microsoft Entra ID는 역할 할당에 사용할 때마다 이 APP ID를 인식할 수 있습니다.

  2. IAM(ID 액세스 관리) – ID 액세스 관리의 일부로 고객은 동의를 제공한 위의 앱 ID에 대한 새 역할 할당을 만듭니다. Data Manager for Agriculture는 센서 파트너라는 새로운 역할을 만듭니다(기존 관리자, 기여자, 읽기 권한자 역할에 추가). 고객은 센서 파트너 역할을 선택하고 파트너 앱 ID를 추가하고 액세스 권한을 제공합니다.

시작

고객은 특정 파트너로부터 센서 데이터를 가져와야 한다는 것을 Data Manager for Agriculture에게 알 수 있도록 했습니다. 그러나 파트너는 센서 데이터를 보내야 하는 고객을 아직 알지 못합니다. 따라서 다음 단계로 고객은 Data Manager for Agriculture 내에서 통합 API를 호출하여 통합 링크를 생성합니다. 통합 링크를 획득한 후 고객은 수동으로 공유하거나 파트너의 포털을 사용하여 아래 정보를 순서대로 공유합니다.

  1. 동의 링크 및 테넌트 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를 확인합니다.

    유효한 응답이 수신되면 파트너는 두 가지 정보 집합을 저장해야 합니다.

    • API 엔드포인트(통합 링크의 첫 번째 부분에서 추출 가능)
    • IntegrationId(GET 호출에 대한 응답의 일부로 반환됨)

    파트너가 이러한 데이터 포인트의 유효성을 검사하고 저장하면 고객은 데이터를 Data Manager for Agriculture에 푸시해야 하는 센서를 추가할 수 있습니다.

  2. 센서/디바이스 추가 – 이제 파트너는 어떤 고객(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를 사용합니다.

모든 센서 원격 분석 이벤트의 경우 "타임스탬프"는 필수 속성이며 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를 테스트합니다.