プラットフォームドキュメント

/

インテグレーション

インテグレーションは、NEQTO.aiを外部のAPIやブローカーに接続します。NEQTO.aiは、指定したサービスのURLと認証情報を使って接続します。プルインテグレーションはNEQTO.aiにデータを取り込み、プッシュインテグレーションはデータを外部に送信します。カスタムインテグレーションは、TLSで保護されたHTTPS、WSS、MQTTSの接続に対応しています。

インテグレーションとデバイスエンドポイントのどちらを使うか?ハードウェアやソフトウェア側からNEQTO.aiに接続する場合は、デバイスエンドポイントを使います。NEQTO.ai側から外部サービスに接続する必要がある場合は、インテグレーションを使います。インテグレーションで取得したデータはデバイスと属性にマッピングでき、ダッシュボード、アラート、分析で使用できます。
NEQTO.aiが認証情報を使って外部のサービスに接続する流れを示す図。インテグレーションは定期的にJSONのペイロードを取り込み、取得したサンプルからAIがフィールドを提案し、それを確定するとインテグレーションと表示されたデバイスが作成され、その測定値がダッシュボードとアラートに使われます。逆方向には、インテグレーションがJSONのペイロードをサービスに送信します。
NEQTO.aiは外部のサービスに接続してJSONをプルまたはプッシュし、サンプルを確定した後、取得した測定値をデバイスにマッピングします。

インテグレーションの場所

アカウントのナビゲーション、またはアプリケーションのサイドバーからインテグレーションを開きます。デフォルトアプリケーションでは、アカウントのすべてのインテグレーションが表示されます。デフォルト以外のアプリケーションでは、そのアプリケーションに紐付いたインテグレーションだけが表示されます。また、そのアカウントまたはアプリケーションで、「インテグレーションを表示」の権限が必要です。

「インテグレーション」画面で、名前、種類、方向、ステータス、デバイス、アプリケーション、操作の列があるインテグレーションの表が表示されています。Facilities API(カスタム・HTTPS・プル)、Plant Telemetry(カスタム・HTTPS・プッシュ)、Rooftop Solar Feed(カスタム・HTTPS・プル)の3行があり、いずれもステータスは下書きでスイッチはオフ、デバイス0、アプリケーションはCold Chain Operationsです。
「インテグレーション」画面には、すべてのコネクターが、プロトコル、方向、ステータスとともに一覧表示されます。

カスタムインテグレーションを作成する

カスタムインテグレーションは、自分で設定するインテグレーションです。ウィザードは種類、プロトコル、認証情報、設定、確認の5つの画面で進みます。

  • 1
    インテグレーションを開き、+(インテグレーションを追加)ボタンをクリックします。種類の画面でカスタムを選ぶと、自分でサービスのURLと認証情報を入力できます。専用のカードがあるサービスの場合は、代わりに標準コネクターの手順を使ってください。カスタムでは、外部プロバイダーのAPI仕様や設定要件を自身で管理します。そのため、プロバイダーのAPIが変わった場合は、インテグレーションを自分で調整する必要があります。

    説明が必要な項目の横には?アイコンがあります。各コネクターのカード、各プロトコル、方向、認証方式、名前です。これを選択すると、その項目の役割と選ぶ際の目安が簡潔に表示されます。

    インテグレーションの種類を選択という見出しのウィザードのステップ1(種類)。種類、プロトコル、認証情報、設定、確認と並ぶ5つのステップの表示があり、その上に連携したいサービスを説明してくださいという入力欄があります。ENERGY STAR Portfolio Manager、天気、カスタムの3枚のカードが縦に並び、それぞれに疑問符のボタンがあって、カスタムがチェックマーク付きで選択されています。
    ステップ1、種類:インテグレーションの種類を選びます。
  • 2
    プロトコルの画面で、TLSの通信方式を選びます。プロバイダーのドキュメントに記載されているものに合わせてください。
    • MQTTSは接続を維持し、トピックでメッセージをやり取りします。継続的にデータを送り続けるブローカーやゲートウェイに向いています。接続先のサービスがMQTTを使用する場合に選びます。
    • HTTPSは、やり取りのたびに1回のリクエストを送ります。設定とデバッグが最も簡単で、ほとんどのプロバイダーのAPIが提供している方式です。RESTやWebhookのAPIの場合に選びます。
    • WSSは1本の接続を維持し、双方向にメッセージを流します。プロバイダーがWebSocketのエンドポイントを公開している場合に選びます。
    プロトコルを選択という見出しと、インテグレーションはTLSで保護された通信方式のみを使うという説明があるウィザードのステップ2(プロトコル)。MQTTS、HTTPS、WSSの3枚のカードが並び、それぞれに疑問符のボタンがあり、まだどれも選択されていません。
    ステップ2、プロトコル:NEQTO.aiの接続方法を選びます。
  • 3
    認証情報の画面で、方向(プル、プッシュ、プル & プッシュ)を設定し、プルとプッシュのどちらかまたは両方のURLを入力し、必要に応じてカスタムのヘッダーを追加します。次に認証方式を選び、その認証情報を入力します。両方の方向を選んだ場合、プルとプッシュには別々のURLを使います。認証方式ごとに必要な項目は、下の表を参照してください。

    プルは、NEQTO.aiがサービスからデータを取り込むことを意味します。MQTTSまたはWSSインテグレーションは、定期サンプルを選ばない限り、接続を維持してすべてのメッセージを保存します。HTTPSインテグレーションは、プルの間隔を設定すると、定期的にリクエストを送ります。プルインテグレーションでは、いつでもサンプルを取得することもできます。プルインテグレーションがデータを受信する方法を参照してください。プッシュは、NEQTO.aiがサービスにデータを送信することを意味します。どちらにも、NEQTO.aiからパブリックインターネット経由でアクセス可能なエンドポイントが必要です。認証方式はNEQTO.aiが外部サービスに対してクライアント認証を行うための仕組みであり、プロバイダー側の指定に従って設定します。プロバイダーのAPIドキュメントを確認してください。誤った方式を選んだ場合は接続テストの時点で失敗するため、事前にエラーを検知できます。

    認証方式の下のTLS証明書では、CA証明書と、クライアント証明書とその秘密鍵を入力します。相互TLSではこのセクションが最初から開いた状態で表示され、入力は必須です。ほかのすべての方式では任意です。TLS証明書を参照してください。

    接続と認証情報という見出しのウィザードのステップ3(認証情報)。方向はプルに設定され、プルURLの欄には例のHTTPSアドレスが入り、任意のヘッダー(JSON)の欄は空で、認証方式はAPIキー、その下のAPIキーの欄は伏せ字になっています。方向と認証方式にはそれぞれ疑問符のボタンがあります。
    ステップ3、認証情報:方向、エンドポイント、認証です。保存した認証情報は暗号化され、再び表示されることはありません。
  • 4
    設定の画面で、インテグレーションに名前と任意の説明を付け、作成をクリックします。インテグレーションの名前はアカウント内で重複できません。名前は一覧、アラート、そのデバイスが表示されるあらゆる場所でこの接続を表すため、どのシステムのどの拠点のものかがわかる名前にしておくと、あとで迷わずに済みます。名前はいつでも変更できます。

    プルするカスタムのMQTTSまたはWSSインテグレーションでは、この画面でデータの受信方法としてサブスクライブまたは定期サンプルも選びます。MQTTSではトピックと、詳細設定の下に任意のクライアントIDが加わります。プルインテグレーションがデータを受信する方法を参照してください。

    インテグレーションは下書きのステータスで始まります。下書きの間も手動でサンプルを取得できますが、有効にするまでサブスクリプション、定期的なプル、プッシュは実行されません。

    設定という見出しのウィザードのステップ4。見出しの下に「インテグレーションに名前を付けます。」という行があります。5つのステップの表示では、確認がまだ先にあります。名前にはRooftop Solar Feedが入り疑問符のボタンがあり、説明にはInverter readings from the rooftop arrayが入っています。注記には、次の確認のステップで接続をテストしてインテグレーションを有効にすること、認証方式でプロバイダー側の承認が必要な場合は確認のステップでインテグレーションの一覧から完了する方法が説明されること、プルインテグレーションの同期間隔は作成後に行の設定を編集で設定することが書かれています。ボタンは戻る、キャンセル、作成です。
    ステップ4、設定:インテグレーションの名前と説明を入力します。
  • 5
    ウィザードは確認に進みます。確認:テストと有効化を参照してください。

Atollaでインテグレーションを下書きする

ウィザードを開くと、「連携したいサービスを説明してください…」という入力欄があります。接続したいサービスを説明すると、Atollaが判断できる範囲で各画面の項目を入力するので、内容を確認して先に進みます。推定した欄には印が付き、自分で入力した内容はそのまま残ります。下書きの動作については、Atollaに質問のガイドを参照してください。

認証方式

6つの方式を使用できます。選んだ方式によって、入力する内容とNEQTO.aiがそれを送る方法が変わります。機密情報はすべて保存時に暗号化され、再び表示されることはありません。

方式 入力する内容 送信方法
APIキー APIキー すべてのリクエストにX-API-Keyヘッダーを付けます。
ベアラートークン トークン すべてのリクエストにAuthorization: Bearerヘッダーを付けます。
Basic認証 ユーザー名とパスワード すべてのリクエストにAuthorization: Basicヘッダーを付けます。
OAuth2(クライアントクレデンシャル) クライアントID、クライアントシークレット、プロバイダーのトークンURL NEQTO.aiがプロバイダーからアクセストークンを自動的に取得し、有効期限が切れるたびに更新します。サインインは必要ありません。
OAuth2(認可コード) クライアントID、クライアントシークレット、トークンURL、プロバイダーの認可URL インテグレーションを作成した後、その行で接続を選び、プロバイダーで一度サインインします。以降は、NEQTO.aiがトークンを自動的に管理して更新します。
相互TLS(mTLS) TLS証明書の項目に、クライアント証明書とその秘密鍵(PEMテキストの貼り付け、またはファイルのアップロード)、および秘密鍵が暗号化されている場合はそのパスフレーズを入力します。MQTTSでは、必要に応じてMQTTユーザー名も入力できます。TLS証明書を参照してください。 クライアント証明書で、TLSの接続そのものを認証します。
認証情報は書き込み専用です。NEQTO.aiは保存した認証情報を暗号化し、再び表示しません。認証情報を編集で、保存済みの機密情報を残すには認証情報(JSON)の欄を空のままにし、置き換えるには完全なJSONオブジェクトを入力します。機密情報を置き換えても、保存済みのTLS証明書は残ります。カスタムのヘッダーは、選んだ認証方式が生成するヘッダーより優先されます。たとえば、カスタムのAuthorizationヘッダーは、BearerやBasicのヘッダーを置き換えます。

トークンを使う認証でのMQTTユーザー名

MQTTSでは、接続するときにブローカーがユーザー名を求めます。トークンはパスワードとしては使用できますが、ユーザー名としては使用できません。そのため、プロトコルがMQTTSで、認証方式がAPIキー、ベアラートークン、OAuth2(クライアントクレデンシャル)、OAuth2(認可コード)のいずれかの場合、認証情報の画面にMQTTユーザー名の欄が加わります。ブローカーが求めるユーザー名を入力してください。トークンはパスワードになります。この欄は必須で、作成のウィザードと行の認証情報を編集の両方に表示されるため、既存のインテグレーションを作り直さずにユーザー名を追加できます。

MQTTSインテグレーションでのインテグレーションを追加ウィザードの認証情報のステップ。方向はプル、プルURLはmqtts://のブローカーのアドレス、認証方式はAPIキーで、その間のMQTTユーザー名の欄にブローカーのユーザー名が入っています。その下のAPIキーの欄は伏せ字になっています。
MQTTSでは、トークンを使う方式でも、ブローカーが求めるMQTTユーザー名を入力します。トークン自体はパスワードになります。

Basic認証には影響しません。すでにユーザー名とパスワードを入力しており、それがそのままブローカーに渡されます。相互TLS(mTLS)は接続そのものを認証します。MQTTSでは、両方を求めるブローカーのために、任意のMQTTユーザー名を入力できます。

プライベート認証局:TLS証明書の下に、PEMのテキスト、ファイル、またはHTTPSのCA証明書のURLとしてCAを追加します。インテグレーションが接続できるのは、公開されている名前解決できるホストだけです。プライベートなアドレスや内部ネットワークのアドレスはブロックされます。

TLS証明書

カスタムインテグレーションにはすべて、ウィザードの認証情報の画面と、行の認証情報を編集にTLS証明書のセクションがあります。どの認証方式とプロトコルでも使用できます。相互TLSでは、クライアント証明書と秘密鍵が必須です。ほかのすべての方式ではこのセクションは任意なので、証明書とパスワードの両方を求めるブローカーにも両方を設定できます。

項目 用途
CA証明書またはCA証明書のURL サーバーの証明書に署名したCAです。プライベートなCA、自己署名のサーバー、中間証明書を送らないサーバーに使います。公開の信頼ストアに追加されるため、公開のサーバーも引き続き検証されます。URLはHTTPSを使い、PEMを返す必要があります。
クライアント証明書 ポート8883でMQTTSを使うAWS IoT Coreなど、証明書を求めるサービスに使います。リーフ証明書を先頭に置き、その後にチェーンを続けます。
秘密鍵 クライアント証明書に対応する鍵です。どちらか一方だけが保存されることはありません。
秘密鍵のパスフレーズ 暗号化された秘密鍵の場合にのみ使います。

-----BEGINで始まるPEMのテキストを貼り付けるか、ファイルをアップロードをクリックして.pem、.crt、.cer、.keyのファイルを選びます。ほかの形式は受け付けません。.p12や.pfxのバンドルは、先に変換してください。

openssl pkcs12 -in cert.p12 -out cert.pem -nodes

出力には証明書と秘密鍵の両方が含まれます。CERTIFICATEのブロックをクライアント証明書に、PRIVATE KEYのブロックを秘密鍵に貼り付けてください。

保存するときに、各項目が確認されます。PEMで64 KB以下であること、CAバンドルの証明書は20件までであること、鍵が証明書と一致しパスフレーズで開けること、クライアント証明書の有効期限が切れていないことが必要です。問題があれば、該当する項目の下に表示されます。

保存後、認証情報を編集には、保存した各証明書のサブジェクト、発行者、有効期限が、置き換えと削除とともに表示されます。秘密鍵とパスフレーズはセキュリティのため再表示されません。クライアント証明書を削除すると、その鍵とパスフレーズも削除されます。有効期限が近い証明書だけを置き換えるには、新しい証明書を貼り付け、保存済みの鍵を残すために鍵の欄は空のままにします。

証明書の検証をオフにするオプションはありません。自己署名のサーバーを信頼するには、その証明書をCA証明書として追加してください。AWS IoT Coreは、ポート8883のMQTTSで、クライアント証明書と、ポリシーで許可されたクライアントIDを使えば動作します。ポート443と、MQTT over WebSocketsのエンドポイントには対応していません。

標準コネクター

標準コネクターは、種類の画面に専用のカードとして表示されます。プロトコル、リクエストの形式、プラットフォームの認証情報はNEQTO.aiが用意します。ウィザードで求められるのは、プロバイダーが必要とするアカウント、認可、または地点だけです。

標準コネクターはENERGY STAR Portfolio Managerと天気です。そのほかのサービスにはカスタムを使ってください。

フリープランとスタータープランには、ENERGY STAR Portfolio Managerや天気などの標準コネクターは含まれていません。カスタムインテグレーションはすべてのプランで利用できます。

インテグレーションを追加ダイアログのステップ1、種類。インテグレーションの種類を選択という見出しと、標準コネクターから始めるか、カスタムで作成するかという説明があります。3枚のカードが縦に並んでいます。ENERGY STAR Portfolio Managerは、プラットフォームアカウントに共有されたプロパティのスコア、エネルギー、排出量のメトリクスを取得すると説明され、天気は、指定した地点の現在の気象状況を取得すると説明され、気象データ提供: Open-Meteo.com(CC BY 4.0)という行があります。カスタムは、独自の認証情報で任意のMQTTS、HTTPS、WSSのエンドポイントに接続するためのものです。下部にキャンセルと無効になった次へのボタンがあります。
標準コネクターは、最初のステップでカスタムと並んで表示されます。環境で利用できないコネクターは表示されません。
注意:ステップの数は選んだカードによって変わります。カスタムは種類 → プロトコル → 認証情報 → 設定 → 確認の順に進みます。ENERGY STARは種類 → 接続 → 設定 → 確認の順に進み、接続のステップでは、認証情報を入力する代わりにアカウントが自分のものであることを証明します。天気は種類 → 設定 → 確認の順に進みます。どの流れも最後は確認で終わります。

ENERGY STAR Portfolio Manager

このコネクターは、Portfolio Managerのアカウントから共有されたプロパティについて、年間のENERGY STARスコア、エネルギー、排出量、水のメトリクスを取得します。NEQTO.aiはプラットフォームが管理するPortfolio Managerのアカウントを使うため、そのアカウントのユーザー名やパスワードをインテグレーションに入力する必要はありません。設定は3つの段階に分かれます。Portfolio Managerでプロパティを準備し、Portfolio ManagerのアカウントをNEQTO.aiに接続し、プロパティをプラットフォームのアカウントと共有します。

Portfolio Managerでプロパティを準備する

NEQTO.aiは、Portfolio Managerがすでに計算したメトリクスを読み取ります。Portfolio Managerがメトリクスを計算するのは、直近に終わった月までの、まる12か月分の請求データがあるメーターを持つプロパティだけです。そのデータがないプロパティも通常どおり接続と共有はできますが、値は得られません。そのため、先にこの段階を済ませてください。

  • 1
    Portfolio Managerにサインインします。MyPortfolioでAdd a Propertyを選びます。
    プロパティがまだないアカウントの、Portfolio ManagerのMyPortfolioタブ。Properties (0)のパネルに、強調表示されたAdd a Propertyボタンがあります。その下のManage Portfolioのパネルには、表計算ファイルからのプロパティのアップロード、ポートフォリオのダウンロード、ベースラインの設定、サンプルのプロパティの追加、プロパティの削除のリンクが並んでいます。右側のパネルでは、アカウントにプロパティがないことが説明され、Set up your first propertyとAdd up to five sample propertiesが示されています。
    すでにPortfolio Managerで建物のベンチマークを行っている場合は、接続の段階に進んでください。12か月分のデータがある既存のプロパティは、そのまま使用できます。
  • 2
    プロパティの種類、建物の数、既存の建物か建設中かを選び、Get Startedを選びます。Basic Property Informationで、名前、住所、建築年、Gross Floor Area、使用中の床面積の割合を入力します。
    Portfolio ManagerのSet Up a Property: Basic Property Informationのページ。About Your Propertyのパネルに入力済みのフォームがあります。Name、United Statesに設定されたCountry、Street Address、City、Massachusettsに設定されたState、Postal Code、Year Built、Sq. Ft.の単位の選択欄とTemporary Valueのチェックボックスが付いたGross Floor Areaです。右側のTipのパネルには、プロパティの名前は重複してもかまわないと書かれています。
    延床面積と使用率は必須です。ENERGY STARスコアもこれらに左右されるため、実際の数値を使ってください。
  • 3
    How is it used?で、建物の種類に応じたプロパティの用途の詳細を入力し、Add Propertyを選びます。星印の付いた項目は、1〜100のENERGY STARスコアに使われます。わからない値にはUse a defaultを使ってかまいません。
    Portfolio Managerのオフィスの用途の詳細の表で、Valueの列が強調表示されています。行には、Gross Floor Area 50,000 Sq. Ft.、Weekly Operating Hours 60、Number of Workers on Main Shift 200、Number of Computers 220、Use a defaultにチェックが入り50 % or moreに設定されたPercent That Can Be CooledとPercent That Can Be Heatedがあります。各行にはCurrent As Ofの日付とTemporary Valueのチェックボックスがあります。下の注記には、この用途の詳細が1〜100のENERGY STAR Scoreの計算に使われると書かれ、Add Propertyボタンが強調表示されています。
    これらの詳細がなくても、Portfolio Managerはエネルギーと排出量のメトリクスを報告しますが、スコアは報告しません。
  • 4
    プロパティのEnergyタブを開き、Add energy use informationを選びます。建物が使うエネルギー源と、それぞれのメーターの数にチェックを入れ、Get Startedを選びます。メーターごとにUnitsとDate Meter became Activeを設定し、Create Metersを選びます。メーターがプロパティのエネルギー使用量の全体をカバーしていることを確認してください。
    Portfolio Managerのプロパティの、Get Started Setting Up Metersのページ。Sources of Your Property's Energyの下で、Electricにチェックが入り、その下のpurchased from the gridにもチェックが入って、How Many Metersは1に設定されています。Natural Gas、Propane、Fuel Oil、Diesel、District Steam、District Hot Water、District Chilled Waterなどのほかのエネルギー源にはチェックが入っていません。横のパネルには、エネルギーの記録方法、敷地内の太陽光や風力にも系統電力のメーターが必要なこと、メーターの入力を自動化する方法が説明されています。
    エネルギー源ごとのメーターは1つで十分です。Portfolio Manager側でそれらを合算し、サイトおよびソースの合計値を算出します。
  • 5
    Manage Billsで、少なくとも直近のまる12か月分について、月ごとに1件ずつ入力し、Save Billsを選びます。各入力はその月の初日から末日までとし、最新の入力は前月の末日で終わるようにします。月の途中から次の月の途中までの請求では、まる12か月をカバーするには13件の入力が必要です。
    Display YearsがShow All Yearsに設定された、Portfolio ManagerのManage BillsのページにあるMonthly Entriesの表。12行に連続した暦月が並び、それぞれ月の初日のStart Date、月の末日のEnd Date、kWhのUsageの値、ドルのTotal Costがあります。Estimation、Demand、Demand Costの列は空です。
    Portfolio Managerでは、すべてのメーターで期間全体のデータがそろうまでメトリクスは利用不可となり、値が算出されると、プロパティのSummaryタブに表示されます。
コネクターを試してみたい場合:Portfolio ManagerのMyPortfolioタブにはAdd up to five sample propertiesがあります。サンプルのプロパティにはメーターのデータがすでに入っているため、すぐにメトリクスが得られます。

Portfolio Managerのアカウントを接続する

  • 1
    NEQTO.aiの種類の画面で、ENERGY STAR Portfolio Managerを選びます。接続のステップに、1回だけ使用できる接続コードとその有効期限が表示されます。
  • 2
    リンクからご自身のPortfolio Managerのアカウントを開きます。Contactsを開き、Add New Contacts/Connectionsを選び、ウィザードに表示されたプラットフォームのアカウントを検索して、Connectを選択します。Neqto Connection Codeの欄にコードを貼り付け、リクエストを送信します。ウィザードが接続を自動的に検出して受け入れます。コードの有効期限が切れた場合は、新しいコードを発行してください。
    ENERGY STARアカウントを接続という見出しの、インテグレーションを追加ダイアログのステップ2、接続。読み取り専用の接続コードの欄にワンタイムコードが表示され、横にコピーボタンがあり、その下に有効期限の日時と、各コードは1回のみ使用できるという行があります。続いて4つの手順が番号付きで並んでいます。ENERGY STAR Portfolio Managerを開くというリンクからご自身のPortfolio Managerアカウントにサインインすること、Contactsを開いてAdd New Contacts/Connectionsからプラットフォームのアカウント名を検索してConnectをクリックすること、接続リクエストフォームのNeqto Connection Codeの欄にコードを貼り付けること、接続リクエストを送信すると以降の確認は自動で行われることです。一覧の下には、接続リクエストを待機していますという回転する表示と、新しいコードを発行ボタンがあります。
    ウィザードはこのステップで待機し、Portfolio Managerがリクエストを送信すると自動的に先に進みます。NEQTO.aiに戻って値を貼り付ける必要はありません。
    Portfolio ManagerのAdd Contactのページ。Connect with an Existing User for Sharingという見出しのパネルに、Name、Organization、Username、Emailの検索欄があり、Usernameの欄にプラットフォームのアカウントのユーザー名が入力され、その下にSearchとCancelの操作があります。Connecting with Other Usersという見出しの横のパネルには、連絡先を検索してConnection Requestを送り、相手が承認するとContactsに加わることが説明されています。
    Usernameで検索します。プラットフォームのアカウント名は、NEQTO.aiのウィザードの接続のステップに表示されます。
    Portfolio Managerの検索結果のページ。結果の行は1つで、プラットフォームのアカウントとその横のConnectボタンがあります。左側のYour Search Criteriaのパネルには、Name、Organization、Username、Email Addressの欄が並び、ユーザー名は入力されたままです。
    結果は1件で、横にConnectがあります。これを選ぶと接続リクエストのフォームが開きます。
    Send a Connection Request to the platform account to Begin Exchanging Dataという見出しの、Portfolio Managerの接続リクエストのフォーム。短い段落で、プロパティとデータをやり取りするためにこのアカウントが次の情報を必要とすることが説明されています。その下に必須のNeqto Connection Codeの欄があり、横にExample: NQ-7F3K-9QD2という文字と、NEQTO.aiのインテグレーションのウィザードに表示された接続コードを貼り付けること、6 - 32文字であることの注記があります。Terms of Useの行にはNone Providedとあり、下部にSend Connection RequestとCancelの操作があります。
    コードは、NEQTO.aiの中ではなく、Portfolio ManagerのリクエストのフォームのNeqto Connection Codeの欄に入力します。
  • 3
    組織でPortfolio Managerのアカウントをすでに確認済みの場合、接続のステップではコードを発行する代わりにそのアカウントが一覧表示されます。プロパティを使いたいアカウントを選ぶか、別のアカウントを接続をクリックします。1つのPortfolio Managerのアカウントは、NEQTO.aiの1つの組織にしか所属できません。
    アカウントの確認後の、インテグレーションを追加ダイアログの接続のステップ。確認済みアカウントの欄には、組織で確認済みのENERGY STARアカウントであること、どれかを選ぶか別のアカウントを接続するよう書かれています。riverside_estates (1001234) というアカウントがラジオボタンで選択された状態で表示され、その下に別のアカウントを接続ボタンがあります。下部に戻る、キャンセル、有効になった次へが並んでいます。
    アカウントを確認すると、接続のステップでは新しいコードを発行する代わりにそのアカウントが一覧表示されます。
  • 4
    設定のステップが開き、確認済みのアカウントが読み取り専用の行で表示されます。そのアカウントがプロパティを共有するまで、プロパティの欄には一覧の代わりに待機中の案内が表示されます。ウィザードを開いたまま、次に説明するとおりにPortfolio Managerでプロパティを共有してください。
    種類と接続に緑のチェックマークが付いた、インテグレーションを追加ダイアログのステップ3、設定。名前(例: Acme Cloud Connector)と説明の欄は空で、接続中のENERGY STARアカウントにriverside_estates (1001234)が表示されています。プロパティの下には、このアカウントから共有されたプロパティはまだないこと、所有者に共有を依頼すると自動的に承認され次回の同期から取得されることが案内されています。メトリクスにはENERGY STARスコア、サイトEUI、ソースEUIなど8つのチェックボックスがすべてチェック付きで並び、単位系は米国慣用単位(EPA)、同期間隔(分)は1440です。下部に戻る、キャンセル、無効になった作成ボタンがあります。
    接続はアカウントが自分のものであることを証明するだけで、それだけでNEQTO.aiがプロパティにアクセスできるようになるわけではありません。

プロパティをプラットフォームのアカウントと共有する

同期したい各プロパティは、Portfolio Managerの中からExchange Dataの権限レベルで共有します。読み取り専用のアクセスで十分です。NEQTO.aiはメトリクスを読み取るだけで、プロパティやメーターに書き込むことはありません。

  • 1
    Portfolio ManagerでSharingタブを開き、Share with your Utility or Service Provider for exchanging dataを選びます。Share (or Edit Access to) a Propertyは、ほかのPortfolio Managerのユーザーと共有するためのものなので、使わないでください。
  • 2
    Select Web Services Providerで、プラットフォームのアカウントを選びます。この一覧には接続済みの連絡先だけが表示されるため、先に接続を済ませてください。Select Propertiesで、同期するプロパティにチェックを入れ、選択を適用します。
  • 3
    Choose PermissionsでBulk Sharingを選び、続いてExchange Data Read Only Accessを選んで、Authorize Exchangeを選びます。
    Portfolio ManagerのShare Properties for Exchanging Dataのページ。Step 1のSelect Web Services Providerでは、連絡先のドロップダウンでプラットフォームのアカウントが選ばれています。Step 2のSelect Propertiesには、Select PropertiesボタンとSelected Properties: 1が表示されています。Step 3のChoose Permissionsでは、Bulk Sharing (Simple Option)が選ばれ、Exchange Data Full Access、Exchange Data Custom Access、Remove Accessの中からExchange Data Read Only Accessが選ばれています。その下にPersonalized Sharing (Custom Orders)の選択肢があり、下部にAuthorize Exchangeボタンがあります。
    Bulk Sharingでは、選択したすべてのプロパティとそのメーターに、同じ権限を一度に適用します。
  • 4
    NEQTO.aiは、通常は数秒以内に共有を自動的に受け入れます。Portfolio ManagerのSharingタブには、プラットフォームが承認したことが記録されます。
    共有したあとのPortfolio ManagerのSharingタブ。My Shared Propertiesに1という数が表示され、その下にShare (or Edit Access to) a Property、Share with your Utility or Service Provider for exchanging data、Download Sharing Reportのボタンがあります。Sharing Notificationsには、プロパティとその電力のメーターが並び、どちらもプラットフォームによって自動的に承認されたため、プラットフォームのアカウントが共有を承認したと記録されています。
    プロパティとそのメーターの両方が承認済みと表示されます。Portfolio Manager側で必要な作業はこれだけです。
なぜ重要か:プロパティが共有されていない状態でも、インテグレーションの設定に不具合があるわけではありません。待機中の状態のまま残り、最初の共有が届くとすぐにプルを始めます。そのため、共有はインテグレーションを作成する前でも後でもかまいません。

NEQTO.aiでインテグレーションを仕上げる

  • 1
    ウィザードに戻り、戻ると次へで設定のステップを更新します。共有したプロパティがプロパティの下に表示されます。インテグレーションに名前を付け、同期するプロパティにチェックを入れます。すべてのプロパティを未選択のままにすると、このアカウントが現在および今後共有するすべてのプロパティが対象になります。代わりに、特定のプロパティを最大200件選ぶこともできます。
  • 2
    メトリクスを1つ以上選び、米国慣用単位(EPA)またはメートル法の単位を選んで、同期間隔を分単位の整数で設定します。デフォルトは1,440分です。プランによっては、より長い間隔が必要になります。報告される各値には、ENERGY STARが返した単位がそのまま付きます。作成をクリックします。
    種類と接続に緑のチェックマークが付いた、インテグレーションを追加ダイアログのステップ3、設定。名前はHarbor Campus Energy、接続中のENERGY STARアカウントはharbor_campus (1005678)です。プロパティにはHarbor Campus Labが1つチェック付きで表示されています。メトリクスには、ENERGY STARスコア、サイトEUI、ソースEUI、サイトエネルギー合計、ソースエネルギー合計、GHG排出量合計、GHG排出原単位、水使用量合計の8つのチェックボックスがすべてチェック付きで2列に並んでいます。単位系は米国慣用単位(EPA)、同期間隔(分)は1440で、下部に戻る、キャンセル、有効になった作成のボタンがあります。
    メトリクス、単位、同期の頻度はインテグレーションに対して一度だけ選び、同期するすべてのプロパティに適用されます。
  • 3
    インテグレーションが下書きとして一覧に表示されます。そのステータスのスイッチをオンにし、「操作」列の3点メニューからサンプルからデバイスを作成を選び、サンプルを取得をクリックします。NEQTO.aiは、プロパティごとに1台、プロパティの名前を付けたデバイスを提案します。デバイスには、Portfolio Managerが報告するメトリクスごとに、その単位とともにフィールドがあります。提案を確認し、デバイスを作成をクリックします。
    上部に新しいサンプルを取得ボタンがある、サンプルからデバイスを作成ダイアログ。デバイス名はHarbor Campus Labで、含める・フィールド・単位・パス・サンプル値の列がある表に、すべてチェック付きの6つのフィールドが並んでいます。kBtu/ft²でサンプル値61.7のsiteIntensity、kBtu/ft²で144.4のsourceIntensity、kBtuで5923200のsiteTotal、kBtuで13860288のsourceTotal、Metric Tonsで313.9のtotalLocationBasedGHGEmissions、kgCO2e/ft²で3.27のtotalLocationBasedGHGEmissionsIntensityで、ダイアログの幅の都合でフィールド名や一部の値は途中で切れています。表の下に生サンプルの切り替え、下部にデバイスを作成とキャンセルのボタンがあります。
    提案されるのは、値のあるメトリクスだけです。この例では、Portfolio Managerがまだ計算していなかったため、スコアと水使用量がありません。
  • 4
    最初のプルが成功すると、有効化待ちが有効に変わり、デバイスの数にはプロパティごとに1台が表示されます。ここからは、デバイスはほかのデバイスと同じように扱えます。ダッシュボード、アラート、エクスポートはすべて使用でき、定期的な同期のたびに値が更新されます。
    行が1つあるインテグレーションの一覧(表のみ)。Harbor Campus Energyの行で、種類は標準、方向はプル、ステータスのスイッチはオンで有効、デバイスは1、アプリケーションはCold Chain Operations、右端に操作の3点メニューがあります。
    1台のデバイスで有効になっています。次の定期的な同期で、最新の年間値が取得されます。

このコネクターで取得できるメトリクスは次の8つです。

  • ENERGY STARスコア
  • サイトとソースのエネルギー使用原単位(EUI)
  • サイトエネルギー合計とソースエネルギー合計
  • ロケーション基準の温室効果ガス排出量合計と排出原単位
  • 水使用量合計
メトリクスの期間:同期のたびに、選択したメトリクスごとに、直近の完了したUTCの月までの12か月分の年間値を1つ取得します。値のないメトリクスは、0として記録されるのではなく、サンプルから除かれます。取得元がまだ値を報告していないとサンプルに表示された場合は、プロパティのメーターに前月末までの請求データがあることを確認してから、新しいサンプルを取得をクリックしてください。

天気

天気のコネクターは、1つの地点の現在の気象状況を定期的に取得し、そのためのデバイスを作成します。気象の測定値は、ダッシュボード、アラート、分析で自分のデータと並べて使用できます。

  • 1
    種類の画面で天気を選びます。ウィザードはそのまま設定に進みます。選ぶプロトコルも、入力する認証情報もありません。
  • 2
    インテグレーションに名前を付け、地点を設定します。都市名、住所、郵便番号を入力して検索をクリックすると、一致した地点が座標とともに一覧表示されます。地点を選ぶまでは何も入力されません。地点を選ぶと緯度と経度が入力され、選択した地点として表示されます。座標を直接入力することもできます。緯度は−90〜90、経度は−180〜180の範囲です。気象状況は座標で取得されるため、地点名はラベルにすぎません。

    近い候補です。内容をご確認くださいと表示された結果は、入力した内容に部分的にしか一致していません。一致する地点がない場合は、「札幌市, 北海道」のように都道府県・州や国を加えるか、座標を入力してください。地点の検索にはGoogle Mapsを使用し、プランの月間ジオコーディング枠を消費します。この枠はマップウィジェットと共有で、結果のない検索も数に入ります。上限に達するとその旨が表示されるので、代わりに座標を入力してください。

    インテグレーションを追加のダイアログにある天気の設定のステップ。名前には大阪の天気と入力されています。地点の検索欄には大阪市と入力され、結果に日本、大阪府大阪市が座標とともに1件表示され、Google Mapsのクレジットがあります。その下の緯度と経度の欄はまだ空で、同期間隔は60です。
    検索で地点を見つけます。座標は、地点を選んだときに初めて入力されます。
  • 3
    同期間隔を分単位で設定し、テストをクリックします。その座標の現在の気象状況が取得されて一覧表示されるため、保存する前に場所が正しいことを確認できます。間隔は、取得元が実際に更新される頻度に合わせてください。プロバイダーが公開するより速くポーリングしても得るものはなく、使える最短の間隔はプランによって決まります。入力済みの値がプランで許される値より短い場合、インテグレーションの作成は「ご利用のプランで設定できる間隔はN分以上です。」というエラーで失敗します。数値を大きくして、もう一度お試しください。
    結果を選んだ後の同じステップ。結果の行の末尾に選択中と表示され、選択した地点:日本、大阪府大阪市という行があり、緯度と経度が入力されています。テストを実行済みで、temperature_2m、relative_humidity_2m、apparent_temperature、precipitation、wind_speed_10m、wind_direction_10m、surface_pressure、cloud_coverの現在の値が一覧表示されています。作成のボタンは有効です。
    地点を選んだ天気の設定のステップ。テストをクリックすると、保存する前にその座標の現在の気象状況を取得します。
  • 4
    作成をクリックします。NEQTO.aiは、インテグレーションとあわせて、標準の気象の属性がマッピング済みの天気デバイスを作成します。
  • 5
    ウィザードは確認に進み、接続をテストしてインテグレーションを有効にできます。ウィザードを閉じて、あとで行から有効にすることもできます。インテグレーションが下書きの間は、定期的な更新は始まりません。
天気のインテグレーションが作成したデバイスの属性タブで、見出しは属性 (8)・ライブです。種類、属性名、表示名、単位の列があり、行は摂氏のtemperature_2m、パーセントのrelative_humidity_2m、摂氏のapparent_temperature、ミリメートルのprecipitation、キロメートル毎時のwind_speed_10m、度のwind_direction_10m、ヘクトパスカルのsurface_pressure、パーセントのcloud_coverです。
天気デバイスと8つの属性。単位は測定値ごとにプロバイダーから届くため、自分で設定するものではありません。

定期的な同期のたびに、次の8つの変数が取り込まれます。

  • 気温と体感温度(体で感じる温度)
  • 相対湿度
  • 降水量
  • 風速と風向
  • 地上気圧
  • 雲量
プロバイダーのアカウントは必要ありません。気象サービスへの接続はNEQTO.aiが管理するため、作成するアカウントも入力するキーもありません。コネクターのカードには、CC BY 4.0ライセンスのもとでOpen-Meteoのクレジットが表示されます。

デバイスの自動設定が完了しなかった場合も、インテグレーションは作成されます。その行の「操作」列の3点メニューを開き、サンプルからデバイスを作成を選んで、手動で仕上げてください。

データをプルしてデバイスを作成する

カスタムのプルインテグレーションでは、サンプルからデバイスを作成を選ぶと、外部のサービスにすぐにリクエストを送ります。HTTPSはGETを使います。WSSは、接続した後の最初のメッセージを待ちます。MQTTSは、インテグレーションのトピックの最初のメッセージを待ちます。トピックのない定期サンプルのMQTTSインテグレーションは、すべてのトピックを受信します。いずれの場合も、最初のペイロードは1 MB以下の1つのJSONオブジェクトでなければなりません。

サンプルからデバイスへ

  • 1
    インテグレーションの「操作」列の3点メニューを開き、サンプルからデバイスを作成を選んでから、サンプルを取得をクリックします。カスタムインテグレーションでは、AIがJSONの構造を調べてフィールドを提案します。標準コネクターでは、代わりにプロバイダーの既知のフィールドを使います。
  • 2
    提案されたデバイス名とフィールドを確認します。フィールドを含めたり外したりでき、名前を変えたり、単位を直したりもできます。変更は提案とともに保存されるため、ダイアログを閉じてあとで戻ることもできます。デバイスを作成せずに提案を却下するには、ごみ箱のボタンをクリックします。
  • 3
    使いたい提案ごとにデバイスを作成をクリックします。NEQTO.aiはデバイスと選択した属性を作成し、インテグレーションと同じアプリケーションに紐付けます。この方法で作成したデバイスには、デバイス一覧のソース列にインテグレーションと表示されます。
新しいサンプルを取得すると、処理中の作業は置き換えられます。提案がすでにある場合、新しいサンプルを取得をクリックすると、それらの提案と編集内容が破棄され、新しい提案が作成されます。すでに確定したデバイスは削除されません。

デバイスの識別子がないカスタムインテグレーションでは、サンプルから1台のデバイスを作成します。アカウントのメタデータのマッピングで識別子のフィールドが定義されている場合、その値がデバイスの外部IDになります。以降のペイロードがそのデバイスに届くには、同じ識別子の値を含んでいる必要があります。NEQTO.aiは最初のデバイスを確定した時点で識別子のパスを固定するため、あとでアカウントのメタデータのマッピングを変更しても、そのインテグレーションの振り分け先は変わりません。

プルインテグレーションがデータを受信する方法

プルするカスタムのMQTTSまたはWSSインテグレーションには、データを受信する方法が2つあります。ウィザードの設定の画面で選び、あとで行の設定を編集で変更できます。

受信方法 動作
サブスクライブ(初期設定) 接続を維持して、すべてのメッセージを保存します。通常は届いてから数秒以内です。同期間隔はなく、プランの月間のプルの上限や最小の間隔には数えられません。接続が切れると自動で再接続し、回復するまで「接続が切れました。再接続しています。」と表示されます。接続が切れても、インテグレーションが無効になることはありません。
定期サンプル 同期間隔(分)ごとに接続し、最初に届いたメッセージを保存します。間隔は必須で、使える最短の間隔はプランによって決まります。

トピック(MQTTS):読み取るMQTTのトピックフィルターです。+は1つの階層に一致し、#はその下のすべての階層に一致して、最後に置く必要があります。たとえばsensors/+/telemetryやplant/#のように書きます。サブスクライブにはトピックが必要です。ここに入力してください。URLの末尾にあるトピックも、#を含めて同じように読み取られます。既存のインテグレーションでは、URLのパスにあるトピックが表示されます。トピックのないMQTTSインテグレーションは定期サンプルとして動作を続け、トピックを追加するとサブスクライブになります。

クライアントID(MQTTS、詳細設定の下):任意です。AWS IoTなど、クライアントIDを制限するブローカーでは、ポリシーで許可されたIDが必要です。設定すると、接続のテスト、サンプル、サブスクリプションのすべてでそのIDを使います。同じIDでもう1つ接続するとサブスクリプションが切断されるため、サブスクリプションの実行中は、接続のテストとサンプルを取得は「サブスクリプションがこのクライアントIDを使用中です。インテグレーションをオフにしてから、もう一度テストしてください。」と表示されて拒否されます。nqai-で始まるIDは、プラットフォームが生成するIDのために予約されています。また、1つのブローカーでは、1つのクライアントIDにつき1つのインテグレーションしか使用できません。23文字までしか受け付けないブローカーもあります。

WSSでは、各メッセージが1つのJSONのペイロードであるWebSocketのストリームが必要です。MQTTのブローカーには、ブローカーがMQTT over WebSocketsも提供している場合でも、MQTTSを選んでください。

サブスクリプションは、インテグレーションが有効な間だけ動作します。インテグレーションをオフにする、削除する、プッシュのみに変更する、または最後のデバイスを削除すると、サブスクリプションは終了します。

HTTPSのプルのスケジュール:ウィザードで作成したHTTPSインテグレーションはプルの間隔なしで始まるため、サンプルを取得したときにだけプルします。定期的にプルするには、行の設定を編集を開き、同期間隔(分)に1〜525,600の整数を入力します。この欄は、インテグレーションにプルURLがある場合に表示されます。使える最短の間隔はプランによって決まり、それより短い値は、プランで許される最小値とともに拒否されます。プランによって、保存した間隔とは別の間隔でインテグレーションが実行される場合は、欄にその旨が表示されます。定期的なプルは、インテグレーションが有効な間だけ実行されます。標準コネクターは、ウィザードで独自の間隔を設定するか、ドキュメントに記載されたデフォルト値を使います。天気とENERGY STARの間隔も、あとで設定を編集で変更できます。

インテグレーションにデータをプッシュする

プッシュまたはプル & プッシュに設定したカスタムインテグレーションは、サービスにJSONのペイロードを送信します。実際の通信の動作は、選んだプロトコルによって決まります。

方向がプッシュまたはプル & プッシュのカスタムインテグレーションは、外部のサービスにJSONのペイロードを送信できます。シリアライズしたペイロードは最大64 KiBです。NEQTO.aiは、インテグレーションに保存された認証とカスタムのヘッダーを適用します。

プロトコル プッシュの動作
HTTPS JSONの本文とContent-Type: application/jsonを付けてPOSTリクエストを送ります。
WSS WebSocketを開き、シリアライズしたJSONを送信してから、接続を閉じます。
MQTTS 設定されたトピック、またはURLのパスにあるトピックにパブリッシュします。トピックは具体的なものでなければなりません。#や+などのワイルドカードを使ったパブリッシュはできません。

アラートのペイロード送信のアクションでは、プッシュに対応し、有効または有効化待ちのHTTPSまたはMQTTSインテグレーションを送信先にできます。アラートが発生したときにWebhookを呼び出すには、WebhookのURLをプッシュURLにしたカスタムHTTPSインテグレーションを作成し、アラートのペイロード送信タブでそのインテグレーションを選んで、アラートを保存します。これで、アラートの送信先のアクションが作成されます。その後で初めて、そのアクションのドライランのダイアログを開いて確認し、ダイアログで承認をクリックし、一覧に戻って有効化できます。承認するには、画面上でドライランを経由する必要があります。インテグレーションを作成しただけでは、アクションは作成されません。有効にした送信先のアラートが発生すると、WebhookはJSONのPOSTを受け取ります。アラートのペイロード送信はWSSに対応していません。ペイロードのテンプレート、送信先の承認、送信先のルールについては、アラートのガイドを参照してください。

定期的な自動プッシュ:インテグレーションの設定に自動プッシュのメッセージと間隔がある場合、NEQTO.aiはそのメッセージを定期的に送信します。使える最短の間隔はプランによって決まります。現在の追加と編集の画面には、自動プッシュの設定は表示されません。

確認:テストと有効化

確認はウィザードの最後の画面で、見出しは「テストと有効化」です。接続の確認、インテグレーションの有効化、最初のデータの確認の3つを順に行います。

考え方:テストと有効化は別々の操作です。接続テストに合格しても、それはサービスが応答したことを示すだけで、データ収集が自動的に始まるわけではありません。有効にするまで、データは集められません。

接続をテストする

接続をテストを選んで実行します。合格すると「接続に成功しました」と表示され、ボタンが再テストに変わるため、ウィザードを離れずに設定を直して再テストできます。失敗すると「接続テストに失敗しました」と、「エンドポイントが認証を拒否しました。」のような理由が表示されます。

カスタムインテグレーションでは、これは行の接続をテストと同じチェックです。接続が成功した後に行われる認証情報の確認も含め、それぞれの結果の意味はそのセクションを参照してください。標準コネクターでは、テストで代わりにプロバイダーに実際のサンプルを取得し、認証情報の確認は行いません。このテストはこの画面にしかなく、行からは使用できません。

インテグレーションを追加ウィザードの確認のステップで、5つのステップのうちステップ5です。見出しはテストと有効化で、接続を確認し、有効にして、最初のデータが届くのを待つという行があります。接続に成功しましたという緑のパネルの上に再テストボタンがあります。パネルの下には、有効化するとデータの収集が始まり、上のテストとは別の操作であるという行があり、その下にインテグレーションを有効化ボタンがあります。
テストに合格しても、インテグレーションは有効になりません。インテグレーションを有効化は、その下に別の操作として表示されます。

プロバイダーでのアクセスの承認が必要な場合

OAuth2(認可コード)を使うインテグレーションでは、プロバイダーのウェブサイトで承認する必要があります。アクセスを承認するまで、確認のテストでは「プロバイダーでの認可が必要です」と表示され、インテグレーションを有効化は表示されません。

接続テストのあとの、インテグレーションを追加ウィザードの確認のステップで、ボタンは再テストになっています。プロバイダーでの認可が必要ですという見出しのパネルが赤枠で囲まれています。パネルには、このインテグレーションはプロバイダー側でアクセスを承認するまで接続できないこと、ウィザードを閉じてインテグレーションの行メニューから接続を選び、プロバイダーにサインインしてリクエストを承認すること、承認するとインテグレーションの一覧に戻ること、同じ行メニューで接続をテストを選んでから行のステータスの列のスイッチをオンにしてインテグレーションを有効化すること、測定値は紐付いたデバイスにしか保存されないため最後に同じ行メニューでサンプルからデバイスを作成を選んで設定することが書かれています。右下に閉じるボタンがあり、インテグレーションを有効化ボタンはありません。
確認のステップでは、プロバイダーでアクセスを承認してインテグレーションを有効にする方法が説明されます。

インテグレーションは、すでに下書きとして保存されています。インテグレーションの一覧から仕上げてください。

  • 1
    閉じるをクリックしてウィザードを閉じます。
  • 2
    インテグレーションの行メニューを開き、接続を選びます。プロバイダーのサインインページに移動します。
    行が1つあるインテグレーションの表。Building Management APIの行で、種類はカスタム・HTTPS、方向はプル、ステータスのスイッチはオフで下書き、デバイスは0、アプリケーションはCold Chain Operationsです。操作の3点メニューが開いていて、設定を編集、認証情報を編集、サンプルからデバイスを作成、接続をテスト、接続、削除が並び、接続が赤枠で囲まれています。
    接続は、OAuth2(認可コード)を使うインテグレーションの行メニューに表示されます。
  • 3
    サインインしてリクエストを承認します。プロバイダーからインテグレーションの一覧に戻ります。
  • 4
    同じ行メニューで接続をテストを選び、行のステータスの列のスイッチをオンにします。プルインテグレーションでは、測定値が保存されるようにするには、さらにサンプルからデバイスを作成が必要です。

接続には、「インテグレーションを編集」の権限が必要です。ロールにその権限がない場合、確認のステップで、権限のあるユーザーにこれらの手順を仕上げてもらうよう案内されます。

インテグレーションを有効にする

インテグレーションを有効化は、テストに合格した後、「有効化するとデータの収集が始まります。上のテストとは別の操作です。」という行の下にだけ表示されます。これを選ぶと、有効化するかまだ有効化しないかの確認を求められるため、接続を確かめるだけで終えることもできます。

有効化しても、すぐに有効のステータスになるわけではありません。ステータスは有効化待ちとなり、まだ接続は有効になっておらず、プロバイダーとの最初のやり取りが成功した時点で有効化されるという注記が表示されます。有効化自体に失敗した場合は、「インテグレーションを有効化できませんでした。ステータスは変更されていません。」と表示され、もう一度ボタンが示されます。

インテグレーションを有効化を選んだあとの同じ確認のステップ。そのボタンが、有効化するとまだ有効化しないの2つのボタンに置き換わり、引き続き有効化するとデータの収集が始まり上のテストとは別の操作であるという行の下に並んでいます。その上の、接続に成功しましたという緑のパネルは変わっていません。
有効化はワンクリックではなく確認を経て行うため、接続をテストしてそこで止めることもできます。

最初のデータを待つ

その後、画面は測定値を監視し、探している間は「最初のデータを待っています…」と表示して、見つかった内容を報告します。以下のどの状態もエラーではありません。

表示 意味
「デバイスが作成されました。最初の測定値を待っています…」と表示され、検出されたデバイスの下のデバイスに「データ未受信」の印が付いている コネクターがデバイスを作成し、NEQTO.aiが測定値を待っています。「データ未受信」のラベルは、測定値が届くと消えます。
「このインテグレーションは接続済みですが、まだデバイスが紐付いていません。」 設定の途中でデバイスを作成しないコネクター(天気以外のすべて)では、想定どおりの表示です。その行メニューでサンプルからデバイスを作成を使ってください。サンプルを取得してもステータスは変わらず、インテグレーションの最初の自動プルで有効になります。HTTPSインテグレーションが自動でプルするのは同期間隔が設定されてからで、サブスクリプションはデバイスが紐付くとメッセージを保存します。プルインテグレーションがデータを受信する方法を参照してください。
「このインテグレーションはソースをサブスクライブしているため、メッセージは届いてから数秒以内に保存されます。」 インテグレーションはサブスクリプションです。ソースが紐付いたデバイスのメッセージを送ると、すぐにデータが表示されます。
「まだデータが届いていません。」 画面は約5分で監視をやめます。インテグレーションは動作を続け、取得元が次にデータを公開したときに、そのデバイスに測定値が表示されます。公開の頻度が低い取得元では、よくあることです。

アプリケーションの中で作業している場合は、デバイスができると次にできることの行にアラートを作成とダッシュボードを作成が表示されます。アプリケーションの外では、この行は表示されません。どちらも、新しいデバイスが選択された状態でその流れを開きます。そこで行うことについては、アラートとダッシュボードのガイドで説明しています。

インテグレーションのステータス

新しいインテグレーションは下書きから始まります。有効にするとステータスは有効化待ちに変わります。最初のプルまたはプッシュが成功すると、ステータスは有効に変わります。カスタムでも標準コネクターでも、インテグレーションをテストしてもステータスは変わらず、サンプルからデバイスを作成でも変わりません。確認:テストと有効化を参照してください。

状況 結果
定期的なプルまたはプッシュで、401、403、またはそのほかの再試行しない4xxの応答を受け取った。HTTP 408と429は再試行の対象として扱われます。 インテグレーションは無効に変わります。サービスが求める認証情報、URL、リクエストを直してから、もう一度有効にしてください。
定期的なプルがレート制限を受けた(429) インテグレーションは有効なままです。サービスがRetry-Afterの期間を示した場合はその期間だけ待ち、示さなかった場合は次の間隔で再試行します。レート制限は、下記の5回の失敗による停止の回数には数えられません。
定期的なプルで408、5xxの応答、またはネットワークのエラーを受け取った NEQTO.aiは次の間隔で再試行します。定期的なプルが5回続けて失敗すると、インテグレーションは無効に変わります。定期的なプルが成功すると、失敗の回数はリセットされます。
定期的なプッシュで408、429、5xxの応答、またはネットワークのエラーを受け取った インテグレーションは有効なままで、プッシュは次の間隔で再試行されます。
サブスクリプションの接続が切れた インテグレーションは有効なままで、再接続するまで「接続が切れました。再接続しています。」と表示されます。接続が切れても、サブスクリプションが無効になることはありません。
ブローカーがトピックを拒否した 最初の試行でインテグレーションは無効に変わり、修正方法がわかる理由が表示されます。トラブルシューティングを参照してください。
TLSのハンドシェイクに失敗した サブスクリプションは有効なままで再試行を続け、証明書の問題がわかる理由が表示されます。どちらかの側で証明書を直すと、自動で再接続します。定期的なプルでは、失敗のたびに接続が切れた場合と同じように数え、5回続けて失敗すると無効に変わります。
手動でのサンプルの取得に失敗した ダイアログにエラーが表示されますが、その失敗でインテグレーションが無効になることはありません。
標準コネクターが、認可またはプロパティの共有を待っている インテグレーションは有効なままで、待っている理由が表示されます。これはプルの失敗には数えられません。

ステータスの列の見方

説明が必要なステータスには、スイッチの横にアイコンが付きます。ポインターを合わせると、その説明の文が表示されます。無効の行には、無効になったときにNEQTO.aiが記録した理由が表示されるため、何を確認すればよいかがわかります。有効化待ちの行には、次のプルまたはプッシュが成功すると有効になることが説明されます。

インテグレーションの表の2行。1行目のFacilities APIは、スイッチがオフで赤い警告のアイコンと無効のステータスがあり、外部サービスがプッシュリクエストを拒否しましたというツールチップが開いています。2行目のPlant Telemetryは、スイッチがオフで砂時計のアイコンと有効化待ちのステータスがあります。
無効になったインテグレーションは、その行に理由が表示されます。有効化待ちのインテグレーションは、何を待っているかが説明されます。

接続をテスト

カスタムインテグレーションの「操作」列の3点メニューにある接続をテストは、保存された認証情報で接続を試みますが、データのプルやプッシュは行いません。標準コネクターでは、NEQTO.aiがエンドポイントと認証情報を管理しているため、この操作はありません。HTTPSでは、401と403以外のどの応答でも到達性のテストに合格します。404でも合格しますが、URLが誤ったリソースを指している可能性があります。WSSとMQTTSでは、それぞれのプロトコルのハンドシェイクが完了する必要があります。両方の方向を持つインテグレーションでは、この最初のテストにプルURLを使います。クライアントIDのあるMQTTSインテグレーションはそのIDでテストするため、サブスクリプションの実行中は、テストの前にインテグレーションをオフにしてください。

接続のテストに成功すると、NEQTO.aiは、わざと無効にした認証情報で設定済みのエンドポイントを確認します。これは、選んだ認証方式によって応答が変わるかどうかを確かめるためです。カスタムのヘッダーやネットワークのアクセスのルールなど、ほかの仕組みでサービスが保護されている場合もあります。テストの結果は次の4つのいずれかです。

表示 意味
「接続に成功しました」 エンドポイントが応答し、保存された認証情報を受け入れ、誤った認証情報を拒否しました。対応は必要ありません。
「接続に成功しました」と、「エンドポイントの認証情報チェックを完了できませんでした。」 接続はできていますが、エンドポイントがタイムアウトした、エラーを返した、または判断できない応答を返したため、認証情報の確認で結論が出ませんでした。結論が必要な場合は、あとでもう一度お試しください。
「エンドポイントが保存された認証情報を拒否しました」 エンドポイントには到達できますが、保存されている認証情報を受け入れません。認証情報を編集で認証情報を更新して、もう一度テストしてください。
「エンドポイントが無効な認証情報を受け入れました」 エンドポイントが、わざと変更した認証情報を受け入れました。設定した認証方式がこのエンドポイントで機能していない可能性があります。ただし、ほかのアクセス制御が適用されている場合もあります。下の警告を参照してください。
接続に成功しましたという文と緑のチェックマーク、閉じるボタンが表示された白い通知トースト。
問題のない結果です。エンドポイントは保存された認証情報を受け入れ、変更した認証情報を拒否しました。
無効な認証情報が受け入れられた場合は、警告として扱ってください。設定した認証方式がこのエンドポイントを保護していることを、テストでは示せませんでした。接続を頼りにする前に、カスタムのヘッダーやネットワークのルールも含め、サービスの認証の設定を確認してください。
エンドポイントが無効な認証情報を受け入れたこと、接続はできるがこのエンドポイントは認証情報を検証していないようであること、データが公開状態になっている恐れがあることを伝える赤い通知。
変更した認証情報が受け入れられました。ほかのアクセス制御でエンドポイントが保護されているか、公開状態になっていないかを確認してください。

インテグレーションの編集と削除

どちらも行の「操作」列の3点メニューから始めます。認証情報の編集では入力した機密情報だけが置き換わり、削除は元に戻せません。

行の「操作」列の3点メニューを開き、設定を編集を選ぶと、名前と説明を変更できます。プルするカスタムのMQTTSまたはWSSインテグレーションでは、データの受信方法、トピック、クライアントIDも設定します。天気では地点も変更できます。地点を変更しても、インテグレーションのデバイスは名前と履歴を含めてそのまま残り、以降の測定値は新しい地点のものになります。認証情報を編集はカスタムインテグレーションで使用でき、入力した機密情報だけを置き換えます。TLS証明書もここで扱います。標準コネクターでは、プロバイダーの認証情報はプラットフォームが管理します。

設定を編集では、複数の方向を選べる場合にだけ方向が表示されます。標準コネクターは常にプルです。カスタムインテグレーションは作成時に設定したURLを使い、編集の画面ではURLを変更できません。プル & プッシュとして作成したインテグレーションは両方のURLを持つため、3つの方向のどれにでも切り替えられます。プルまたはプッシュとして作成したインテグレーションは、その方向のままです。

Plant Telemetryの設定を編集ダイアログ。名前、説明、方向の欄と、キャンセルと保存のボタンがあります。方向の欄が赤枠で囲まれ、プル & プッシュに設定されています。その一覧が開いていて、プル、プッシュ、プル & プッシュの3つの選択肢があり、プル & プッシュにチェックが付いています。開いた一覧の陰に、同期間隔の欄の一部が見えています。
プル & プッシュとして作成したインテグレーションは両方のURLを持つため、3つの方向のどれにでも切り替えられます。
インテグレーションの削除は元に戻せません。削除すると、そのプルと自動プッシュのスケジュールが止まり、アプリケーションとの紐付けと、そこから作成したデバイスとの紐付けが削除されます。それらのデバイスと保存された測定値はNEQTO.aiに残りますが、削除したインテグレーションから新しいデータが届くことはなくなります。デバイスが不要になった場合は、別に削除してください。

権限

作業 必要な権限
一覧を開き、保存された提案を見る インテグレーションを表示
インテグレーションを作成する インテグレーションを作成
編集、接続、テスト、ステータスの変更、サンプルの取得 インテグレーションを編集
サンプルの操作を開き、提案をデバイスとして確定する インテグレーションを編集とデバイスを作成
インテグレーションを削除する インテグレーションを削除

NEQTO.aiは、アカウントレベルの画面ではアカウントの権限を、アプリケーションの中ではアプリケーションの権限を確認します。権限がない場合は、操作が表示されないか、リクエストが拒否されます。

例:自分のサービスからプルする

カスタムのプルの流れをテストするときは、応答を確認でき、リクエストを繰り返せるよう、自分で管理しているサービスを使ってください。

  • 1
    現在の測定値を1つのJSONオブジェクトで返すHTTPSのURLを1つ公開します。ネストしたフィールドにも対応していますが、フラットな構造の応答のほうが、提案されたフィールドを確認しやすくなります。
    {
      "meter_id": "MTR-114",
      "power_kw": 8.4,
      "energy_kwh": 15230.7,
      "temperature_c": 41.2
    }
  • 2
    種類はカスタム、プロトコルはHTTPS、方向はプル、URLはそのURL、認証方式はサービスが求めるものにして、インテグレーションを作成します。次に接続をテストを実行して到達性を確認します。認証情報の確認で結論が出れば、エンドポイントが保存された認証情報を受け入れ、変更した認証情報を拒否するかどうかも確認できます。
  • 3
    サンプルからデバイスを作成を開き、サンプルを取得して、提案されたフィールドを確定します。これでデバイスが作成されます。以降の手動のサンプルも同じエンドポイントを使います。定期的にプルするには、上で説明したとおり、行の設定を編集で同期間隔を設定します。
気象データが必要な場合:カスタムのプルではなく、天気のコネクターを使ってください。自分のAPIキーが不要で、デバイスも自動で作成されます。

トラブルシューティング

以下の各メッセージは、NEQTO.aiができなかったことと、再試行する前に変えるべきことを示しています。

メッセージ 意味
「外部サービスからのデータの取得に失敗しました。」 サービスに到達できなかった、タイムアウトした、またはエラーのステータスが返されました。URLとサービスが稼働していることを確認してから、もう一度プルしてください。
「外部サービスがJSONオブジェクトを返しませんでした。」 応答が1つのJSONオブジェクトではありませんでした(プレーンテキスト、HTML、配列だけなど)。JSONオブジェクトを返すエンドポイントをURLに指定してください。
「外部サービスがインテグレーションの認証情報を拒否しました。」 サービスが認証のエラー(401または403)で応答しました。インテグレーションの設定で認証情報を更新してください。
「OAuth接続が必要です。このインテグレーションを再度接続してください。」 保存されているOAuthのセッションを更新できなくなりました(プロバイダーでアクセスが取り消された場合など)。インテグレーションの行で接続を選び、もう一度サインインしてください。
「ENERGY STARのプロパティがプラットフォームアカウントと共有されるのを待っています。」 Portfolio Managerのアカウントの接続は確認済みですが、まだプロパティが共有されていません。プロパティをプラットフォームのアカウントと共有してください。NEQTO.aiは共有を自動的に受け入れ、次の同期で再試行します。
「プロバイダーがこのレコードの値をまだ公開していません。」 標準コネクターは取得元のレコードを見つけましたが、使用できるメトリクスの値がありませんでした。プロバイダーがデータを公開してから、新しいサンプルを取得してください。
「サンプル内に、デバイス識別子として使用できるオブジェクトがありませんでした。」 アカウントのメタデータのマッピングで設定された識別子のフィールドが、サンプルにない、空である、または文字列、数値、真偽値のいずれでもありません。応答またはマッピングを直してから、新しいサンプルを取得してください。
「この識別子を持つデバイスは、このアカウントに既に存在します。」 提案された外部IDは、すでに別のデバイスが使っています。既存のデバイスを使うか、取得元の識別子を変えてください。無効にしたデバイスも、完全に削除されるまでは外部IDを確保したままです。
「外部サービスがプッシュリクエストを拒否しました。」 サービスがプッシュに対して、認証のエラー以外のエラーのステータスで応答しました。プッシュURLと、サービスが求めるペイロードの形式を確認してください。
「プル間隔がプランの下限を下回っています。」 / 「自動プッシュの間隔がプランの下限を下回っています。」 間隔を長くするか、より短い間隔についてサポートにお問い合わせください。
「MQTTのプッシュトピックには、#や+などのワイルドカードを含まない具体的なトピックを指定する必要があります。」 ワイルドカードを、ペイロードをパブリッシュする正確なトピックに置き換えてください。
「certificateUrlからPEM証明書を取得できませんでした。」 CA証明書のURLを取得できなかったか、PEMの証明書が返されませんでした。URLを確認するか、認証情報を編集のTLS証明書にCAを貼り付けてください。
「サーバーの証明書が信頼されていません。署名したCA証明書を追加してください。」 サーバーの証明書が公に信頼されていないCAによって署名されているか、サーバーが中間証明書を送っていません。そのCAをTLS証明書に追加してください。サブスクリプションは自動で再接続します。無効になった定期的なプルは、もう一度有効にしてください。
「サーバーの証明書は有効期限が切れているか、まだ有効になっていません。」 サーバーの証明書を更新する必要があります。サービスの運用者に問い合わせてください。
「サーバーの証明書がホスト名と一致しません。」 URLのホストが、証明書の対象に含まれていません。証明書が発行されたホスト名を使ってください。
「サーバーがクライアント証明書を拒否しました。」 サーバーは、信頼できるクライアント証明書を求めています。TLS証明書で証明書を追加するか置き換え、有効期限が切れていないことを確認してください。
「ブローカーがこのトピックへのサブスクライブを拒否しました。」 ブローカーが、この接続にトピックの読み取りを許可していません。トピック、クライアントID、この認証情報に対するブローカーの権限を確認してください。
「サブスクリプションがこのクライアントIDを使用中です。インテグレーションをオフにしてから、もう一度テストしてください。」 接続のテストやサンプルの取得を行うと、実行中のサブスクリプションが切断されます。インテグレーションをオフにしてテストし、その後オンに戻してください。

制限とセキュリティ

すべてのインテグレーションに適用される上限とネットワークのルールです。

項目 上限
接続のセキュリティ TLSのみです(HTTPS、WSS、MQTTS)。暗号化されていないHTTP、WS、MQTTには対応していません。
接続できるホスト 公開されているホストのみです。プライベートなアドレスと内部ネットワークのアドレスはブロックされます。
接続のタイムアウト HTTPS、WSS、MQTTSの接続処理は15秒です。
カスタムのプルの応答 最大1 MBで、応答は1つのJSONオブジェクトである必要があります。
サブスクライブしたメッセージ 1件のメッセージにつき最大1 MBです。
プッシュのペイロード JSONにシリアライズした後で最大64 KiBです。
プルと自動プッシュの間隔 最小の間隔はプランによって変わります。サブスクリプションには間隔がなく、月間のプルの上限にも数えられません。
インテグレーションの数 プランにデバイスの上限がない限り、上限はありません。デバイスの上限がある場合、アカウントとそのサブアカウントで、その数までインテグレーションを作成できます。
名前と説明 名前は100文字以内で、アカウント内で重複できません。説明は500文字以内です。
提案されるフィールド デバイスの提案1件につき最大50フィールドです。
ENERGY STARのプロパティ 明示的に選べるのは最大200件です。何も選ばない場合は、共有されたすべてのプロパティが対象になります。
CA証明書のURL HTTPSのみで、最大2,048文字です。PEMの取得は10秒でタイムアウトし、最大64 KiBまで受け付けます。
TLS証明書 PEMのみで、1項目につき最大64 KB、CAバンドルの証明書は最大20件です。証明書の検証は常にオンです。
MQTTのトピックとクライアントID トピックは512文字以内です。クライアントIDは、空白を含まない1〜128文字の印字可能なASCII文字で、nqai-で始まらず、1つのブローカーにつき1つのインテグレーションで使います。
カスタムのヘッダー JSONオブジェクトで入力します。ヘッダーとして送信されるのは、文字列と数値の値だけです。
保存された認証情報 保存時に暗号化され、書き込み専用で、保存後に返されることはありません。秘密鍵とパスフレーズは、返されることも、チャットに渡されることもありません。