インテグレーション
インテグレーションは、NEQTO.aiを外部のAPIやブローカーに接続します。NEQTO.aiは、指定したサービスのURLと認証情報を使って接続します。プルインテグレーションはNEQTO.aiにデータを取り込み、プッシュインテグレーションはデータを外部に送信します。カスタムインテグレーションは、TLSで保護されたHTTPS、WSS、MQTTSの接続に対応しています。
インテグレーションの場所
アカウントのナビゲーション、またはアプリケーションのサイドバーからインテグレーションを開きます。デフォルトアプリケーションでは、アカウントのすべてのインテグレーションが表示されます。デフォルト以外のアプリケーションでは、そのアプリケーションに紐付いたインテグレーションだけが表示されます。また、そのアカウントまたはアプリケーションで、「インテグレーションを表示」の権限が必要です。
カスタムインテグレーションを作成する
カスタムインテグレーションは、自分で設定するインテグレーションです。ウィザードは種類、プロトコル、認証情報、設定、確認の5つの画面で進みます。
-
1インテグレーションを開き、+(インテグレーションを追加)ボタンをクリックします。種類の画面でカスタムを選ぶと、自分でサービスのURLと認証情報を入力できます。専用のカードがあるサービスの場合は、代わりに標準コネクターの手順を使ってください。カスタムでは、外部プロバイダーのAPI仕様や設定要件を自身で管理します。そのため、プロバイダーのAPIが変わった場合は、インテグレーションを自分で調整する必要があります。
説明が必要な項目の横には?アイコンがあります。各コネクターのカード、各プロトコル、方向、認証方式、名前です。これを選択すると、その項目の役割と選ぶ際の目安が簡潔に表示されます。
ステップ1、種類:インテグレーションの種類を選びます。 -
2プロトコルの画面で、TLSの通信方式を選びます。プロバイダーのドキュメントに記載されているものに合わせてください。
- MQTTSは接続を維持し、トピックでメッセージをやり取りします。継続的にデータを送り続けるブローカーやゲートウェイに向いています。接続先のサービスがMQTTを使用する場合に選びます。
- HTTPSは、やり取りのたびに1回のリクエストを送ります。設定とデバッグが最も簡単で、ほとんどのプロバイダーのAPIが提供している方式です。RESTやWebhookのAPIの場合に選びます。
- WSSは1本の接続を維持し、双方向にメッセージを流します。プロバイダーがWebSocketのエンドポイントを公開している場合に選びます。
ステップ2、プロトコル:NEQTO.aiの接続方法を選びます。 -
3認証情報の画面で、方向(プル、プッシュ、プル & プッシュ)を設定し、プルとプッシュのどちらかまたは両方のURLを入力し、必要に応じてカスタムのヘッダーを追加します。次に認証方式を選び、その認証情報を入力します。両方の方向を選んだ場合、プルとプッシュには別々のURLを使います。認証方式ごとに必要な項目は、下の表を参照してください。
プルは、NEQTO.aiがサービスからデータを取り込むことを意味します。MQTTSまたはWSSインテグレーションは、定期サンプルを選ばない限り、接続を維持してすべてのメッセージを保存します。HTTPSインテグレーションは、プルの間隔を設定すると、定期的にリクエストを送ります。プルインテグレーションでは、いつでもサンプルを取得することもできます。プルインテグレーションがデータを受信する方法を参照してください。プッシュは、NEQTO.aiがサービスにデータを送信することを意味します。どちらにも、NEQTO.aiからパブリックインターネット経由でアクセス可能なエンドポイントが必要です。認証方式はNEQTO.aiが外部サービスに対してクライアント認証を行うための仕組みであり、プロバイダー側の指定に従って設定します。プロバイダーのAPIドキュメントを確認してください。誤った方式を選んだ場合は接続テストの時点で失敗するため、事前にエラーを検知できます。
認証方式の下のTLS証明書では、CA証明書と、クライアント証明書とその秘密鍵を入力します。相互TLSではこのセクションが最初から開いた状態で表示され、入力は必須です。ほかのすべての方式では任意です。TLS証明書を参照してください。
ステップ3、認証情報:方向、エンドポイント、認証です。保存した認証情報は暗号化され、再び表示されることはありません。 -
4設定の画面で、インテグレーションに名前と任意の説明を付け、作成をクリックします。インテグレーションの名前はアカウント内で重複できません。名前は一覧、アラート、そのデバイスが表示されるあらゆる場所でこの接続を表すため、どのシステムのどの拠点のものかがわかる名前にしておくと、あとで迷わずに済みます。名前はいつでも変更できます。
プルするカスタムのMQTTSまたはWSSインテグレーションでは、この画面でデータの受信方法としてサブスクライブまたは定期サンプルも選びます。MQTTSではトピックと、詳細設定の下に任意のクライアントIDが加わります。プルインテグレーションがデータを受信する方法を参照してください。
インテグレーションは下書きのステータスで始まります。下書きの間も手動でサンプルを取得できますが、有効にするまでサブスクリプション、定期的なプル、プッシュは実行されません。
ステップ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の接続そのものを認証します。 |
Authorizationヘッダーは、BearerやBasicのヘッダーを置き換えます。
トークンを使う認証でのMQTTユーザー名
MQTTSでは、接続するときにブローカーがユーザー名を求めます。トークンはパスワードとしては使用できますが、ユーザー名としては使用できません。そのため、プロトコルがMQTTSで、認証方式がAPIキー、ベアラートークン、OAuth2(クライアントクレデンシャル)、OAuth2(認可コード)のいずれかの場合、認証情報の画面にMQTTユーザー名の欄が加わります。ブローカーが求めるユーザー名を入力してください。トークンはパスワードになります。この欄は必須で、作成のウィザードと行の認証情報を編集の両方に表示されるため、既存のインテグレーションを作り直さずにユーザー名を追加できます。
Basic認証には影響しません。すでにユーザー名とパスワードを入力しており、それがそのままブローカーに渡されます。相互TLS(mTLS)は接続そのものを認証します。MQTTSでは、両方を求めるブローカーのために、任意のMQTTユーザー名を入力できます。
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や天気などの標準コネクターは含まれていません。カスタムインテグレーションはすべてのプランで利用できます。
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か月分の請求データがあるメーターを持つプロパティだけです。そのデータがないプロパティも通常どおり接続と共有はできますが、値は得られません。そのため、先にこの段階を済ませてください。
-
1Portfolio Managerにサインインします。MyPortfolioでAdd a Propertyを選びます。
すでにPortfolio Managerで建物のベンチマークを行っている場合は、接続の段階に進んでください。12か月分のデータがある既存のプロパティは、そのまま使用できます。 -
2プロパティの種類、建物の数、既存の建物か建設中かを選び、Get Startedを選びます。Basic Property Informationで、名前、住所、建築年、Gross Floor Area、使用中の床面積の割合を入力します。
延床面積と使用率は必須です。ENERGY STARスコアもこれらに左右されるため、実際の数値を使ってください。 -
3How is it used?で、建物の種類に応じたプロパティの用途の詳細を入力し、Add Propertyを選びます。星印の付いた項目は、1〜100のENERGY STARスコアに使われます。わからない値にはUse a defaultを使ってかまいません。
これらの詳細がなくても、Portfolio Managerはエネルギーと排出量のメトリクスを報告しますが、スコアは報告しません。 -
4プロパティのEnergyタブを開き、Add energy use informationを選びます。建物が使うエネルギー源と、それぞれのメーターの数にチェックを入れ、Get Startedを選びます。メーターごとにUnitsとDate Meter became Activeを設定し、Create Metersを選びます。メーターがプロパティのエネルギー使用量の全体をカバーしていることを確認してください。
エネルギー源ごとのメーターは1つで十分です。Portfolio Manager側でそれらを合算し、サイトおよびソースの合計値を算出します。 -
5Manage Billsで、少なくとも直近のまる12か月分について、月ごとに1件ずつ入力し、Save Billsを選びます。各入力はその月の初日から末日までとし、最新の入力は前月の末日で終わるようにします。月の途中から次の月の途中までの請求では、まる12か月をカバーするには13件の入力が必要です。
Portfolio Managerでは、すべてのメーターで期間全体のデータがそろうまでメトリクスは利用不可となり、値が算出されると、プロパティのSummaryタブに表示されます。
Portfolio Managerのアカウントを接続する
-
1NEQTO.aiの種類の画面で、ENERGY STAR Portfolio Managerを選びます。接続のステップに、1回だけ使用できる接続コードとその有効期限が表示されます。
-
2リンクからご自身のPortfolio Managerのアカウントを開きます。Contactsを開き、Add New Contacts/Connectionsを選び、ウィザードに表示されたプラットフォームのアカウントを検索して、Connectを選択します。
Neqto Connection Codeの欄にコードを貼り付け、リクエストを送信します。ウィザードが接続を自動的に検出して受け入れます。コードの有効期限が切れた場合は、新しいコードを発行してください。
ウィザードはこのステップで待機し、Portfolio Managerがリクエストを送信すると自動的に先に進みます。NEQTO.aiに戻って値を貼り付ける必要はありません。
Usernameで検索します。プラットフォームのアカウント名は、NEQTO.aiのウィザードの接続のステップに表示されます。
結果は1件で、横にConnectがあります。これを選ぶと接続リクエストのフォームが開きます。
コードは、NEQTO.aiの中ではなく、Portfolio Managerのリクエストのフォームの Neqto Connection Codeの欄に入力します。 -
3組織でPortfolio Managerのアカウントをすでに確認済みの場合、接続のステップではコードを発行する代わりにそのアカウントが一覧表示されます。プロパティを使いたいアカウントを選ぶか、別のアカウントを接続をクリックします。1つのPortfolio Managerのアカウントは、NEQTO.aiの1つの組織にしか所属できません。
アカウントを確認すると、接続のステップでは新しいコードを発行する代わりにそのアカウントが一覧表示されます。 -
4設定のステップが開き、確認済みのアカウントが読み取り専用の行で表示されます。そのアカウントがプロパティを共有するまで、プロパティの欄には一覧の代わりに待機中の案内が表示されます。ウィザードを開いたまま、次に説明するとおりにPortfolio Managerでプロパティを共有してください。
接続はアカウントが自分のものであることを証明するだけで、それだけでNEQTO.aiがプロパティにアクセスできるようになるわけではありません。
プロパティをプラットフォームのアカウントと共有する
同期したい各プロパティは、Portfolio Managerの中からExchange Dataの権限レベルで共有します。読み取り専用のアクセスで十分です。NEQTO.aiはメトリクスを読み取るだけで、プロパティやメーターに書き込むことはありません。
-
1Portfolio ManagerでSharingタブを開き、Share with your Utility or Service Provider for exchanging dataを選びます。Share (or Edit Access to) a Propertyは、ほかのPortfolio Managerのユーザーと共有するためのものなので、使わないでください。
-
2Select Web Services Providerで、プラットフォームのアカウントを選びます。この一覧には接続済みの連絡先だけが表示されるため、先に接続を済ませてください。Select Propertiesで、同期するプロパティにチェックを入れ、選択を適用します。
-
3Choose PermissionsでBulk Sharingを選び、続いてExchange Data Read Only Accessを選んで、Authorize Exchangeを選びます。
Bulk Sharingでは、選択したすべてのプロパティとそのメーターに、同じ権限を一度に適用します。 -
4NEQTO.aiは、通常は数秒以内に共有を自動的に受け入れます。Portfolio ManagerのSharingタブには、プラットフォームが承認したことが記録されます。
プロパティとそのメーターの両方が承認済みと表示されます。Portfolio Manager側で必要な作業はこれだけです。
NEQTO.aiでインテグレーションを仕上げる
-
1ウィザードに戻り、戻ると次へで設定のステップを更新します。共有したプロパティがプロパティの下に表示されます。インテグレーションに名前を付け、同期するプロパティにチェックを入れます。すべてのプロパティを未選択のままにすると、このアカウントが現在および今後共有するすべてのプロパティが対象になります。代わりに、特定のプロパティを最大200件選ぶこともできます。
-
2メトリクスを1つ以上選び、米国慣用単位(EPA)またはメートル法の単位を選んで、同期間隔を分単位の整数で設定します。デフォルトは1,440分です。プランによっては、より長い間隔が必要になります。報告される各値には、ENERGY STARが返した単位がそのまま付きます。作成をクリックします。
メトリクス、単位、同期の頻度はインテグレーションに対して一度だけ選び、同期するすべてのプロパティに適用されます。 -
3インテグレーションが下書きとして一覧に表示されます。そのステータスのスイッチをオンにし、「操作」列の3点メニューからサンプルからデバイスを作成を選び、サンプルを取得をクリックします。NEQTO.aiは、プロパティごとに1台、プロパティの名前を付けたデバイスを提案します。デバイスには、Portfolio Managerが報告するメトリクスごとに、その単位とともにフィールドがあります。提案を確認し、デバイスを作成をクリックします。
提案されるのは、値のあるメトリクスだけです。この例では、Portfolio Managerがまだ計算していなかったため、スコアと水使用量がありません。 -
4最初のプルが成功すると、有効化待ちが有効に変わり、デバイスの数にはプロパティごとに1台が表示されます。ここからは、デバイスはほかのデバイスと同じように扱えます。ダッシュボード、アラート、エクスポートはすべて使用でき、定期的な同期のたびに値が更新されます。
1台のデバイスで有効になっています。次の定期的な同期で、最新の年間値が取得されます。
このコネクターで取得できるメトリクスは次の8つです。
- ENERGY STARスコア
- サイトとソースのエネルギー使用原単位(EUI)
- サイトエネルギー合計とソースエネルギー合計
- ロケーション基準の温室効果ガス排出量合計と排出原単位
- 水使用量合計
天気
天気のコネクターは、1つの地点の現在の気象状況を定期的に取得し、そのためのデバイスを作成します。気象の測定値は、ダッシュボード、アラート、分析で自分のデータと並べて使用できます。
-
1種類の画面で天気を選びます。ウィザードはそのまま設定に進みます。選ぶプロトコルも、入力する認証情報もありません。
-
2インテグレーションに名前を付け、地点を設定します。都市名、住所、郵便番号を入力して検索をクリックすると、一致した地点が座標とともに一覧表示されます。地点を選ぶまでは何も入力されません。地点を選ぶと緯度と経度が入力され、選択した地点として表示されます。座標を直接入力することもできます。緯度は−90〜90、経度は−180〜180の範囲です。気象状況は座標で取得されるため、地点名はラベルにすぎません。
近い候補です。内容をご確認くださいと表示された結果は、入力した内容に部分的にしか一致していません。一致する地点がない場合は、「札幌市, 北海道」のように都道府県・州や国を加えるか、座標を入力してください。地点の検索にはGoogle Mapsを使用し、プランの月間ジオコーディング枠を消費します。この枠はマップウィジェットと共有で、結果のない検索も数に入ります。上限に達するとその旨が表示されるので、代わりに座標を入力してください。
検索で地点を見つけます。座標は、地点を選んだときに初めて入力されます。 -
3同期間隔を分単位で設定し、テストをクリックします。その座標の現在の気象状況が取得されて一覧表示されるため、保存する前に場所が正しいことを確認できます。間隔は、取得元が実際に更新される頻度に合わせてください。プロバイダーが公開するより速くポーリングしても得るものはなく、使える最短の間隔はプランによって決まります。入力済みの値がプランで許される値より短い場合、インテグレーションの作成は「ご利用のプランで設定できる間隔はN分以上です。」というエラーで失敗します。数値を大きくして、もう一度お試しください。
地点を選んだ天気の設定のステップ。テストをクリックすると、保存する前にその座標の現在の気象状況を取得します。 -
4作成をクリックします。NEQTO.aiは、インテグレーションとあわせて、標準の気象の属性がマッピング済みの天気デバイスを作成します。
-
5ウィザードは確認に進み、接続をテストしてインテグレーションを有効にできます。ウィザードを閉じて、あとで行から有効にすることもできます。インテグレーションが下書きの間は、定期的な更新は始まりません。
定期的な同期のたびに、次の8つの変数が取り込まれます。
- 気温と体感温度(体で感じる温度)
- 相対湿度
- 降水量
- 風速と風向
- 地上気圧
- 雲量
デバイスの自動設定が完了しなかった場合も、インテグレーションは作成されます。その行の「操作」列の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を選んでください。
サブスクリプションは、インテグレーションが有効な間だけ動作します。インテグレーションをオフにする、削除する、プッシュのみに変更する、または最後のデバイスを削除すると、サブスクリプションは終了します。
インテグレーションにデータをプッシュする
プッシュまたはプル & プッシュに設定したカスタムインテグレーションは、サービスに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に対応していません。ペイロードのテンプレート、送信先の承認、送信先のルールについては、アラートのガイドを参照してください。
確認:テストと有効化
確認はウィザードの最後の画面で、見出しは「テストと有効化」です。接続の確認、インテグレーションの有効化、最初のデータの確認の3つを順に行います。
接続をテストする
接続をテストを選んで実行します。合格すると「接続に成功しました」と表示され、ボタンが再テストに変わるため、ウィザードを離れずに設定を直して再テストできます。失敗すると「接続テストに失敗しました」と、「エンドポイントが認証を拒否しました。」のような理由が表示されます。
カスタムインテグレーションでは、これは行の接続をテストと同じチェックです。接続が成功した後に行われる認証情報の確認も含め、それぞれの結果の意味はそのセクションを参照してください。標準コネクターでは、テストで代わりにプロバイダーに実際のサンプルを取得し、認証情報の確認は行いません。このテストはこの画面にしかなく、行からは使用できません。
プロバイダーでのアクセスの承認が必要な場合
OAuth2(認可コード)を使うインテグレーションでは、プロバイダーのウェブサイトで承認する必要があります。アクセスを承認するまで、確認のテストでは「プロバイダーでの認可が必要です」と表示され、インテグレーションを有効化は表示されません。
インテグレーションは、すでに下書きとして保存されています。インテグレーションの一覧から仕上げてください。
-
1閉じるをクリックしてウィザードを閉じます。
-
2インテグレーションの行メニューを開き、接続を選びます。プロバイダーのサインインページに移動します。
接続は、OAuth2(認可コード)を使うインテグレーションの行メニューに表示されます。 -
3サインインしてリクエストを承認します。プロバイダーからインテグレーションの一覧に戻ります。
-
4同じ行メニューで接続をテストを選び、行のステータスの列のスイッチをオンにします。プルインテグレーションでは、測定値が保存されるようにするには、さらにサンプルからデバイスを作成が必要です。
接続には、「インテグレーションを編集」の権限が必要です。ロールにその権限がない場合、確認のステップで、権限のあるユーザーにこれらの手順を仕上げてもらうよう案内されます。
インテグレーションを有効にする
インテグレーションを有効化は、テストに合格した後、「有効化するとデータの収集が始まります。上のテストとは別の操作です。」という行の下にだけ表示されます。これを選ぶと、有効化するかまだ有効化しないかの確認を求められるため、接続を確かめるだけで終えることもできます。
有効化しても、すぐに有効のステータスになるわけではありません。ステータスは有効化待ちとなり、まだ接続は有効になっておらず、プロバイダーとの最初のやり取りが成功した時点で有効化されるという注記が表示されます。有効化自体に失敗した場合は、「インテグレーションを有効化できませんでした。ステータスは変更されていません。」と表示され、もう一度ボタンが示されます。
最初のデータを待つ
その後、画面は測定値を監視し、探している間は「最初のデータを待っています…」と表示して、見つかった内容を報告します。以下のどの状態もエラーではありません。
| 表示 | 意味 |
|---|---|
| 「デバイスが作成されました。最初の測定値を待っています…」と表示され、検出されたデバイスの下のデバイスに「データ未受信」の印が付いている | コネクターがデバイスを作成し、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が記録した理由が表示されるため、何を確認すればよいかがわかります。有効化待ちの行には、次のプルまたはプッシュが成功すると有効になることが説明されます。
接続をテスト
カスタムインテグレーションの「操作」列の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つの方向のどれにでも切り替えられます。プルまたはプッシュとして作成したインテグレーションは、その方向のままです。
権限
| 作業 | 必要な権限 |
|---|---|
| 一覧を開き、保存された提案を見る | インテグレーションを表示 |
| インテグレーションを作成する | インテグレーションを作成 |
| 編集、接続、テスト、ステータスの変更、サンプルの取得 | インテグレーションを編集 |
| サンプルの操作を開き、提案をデバイスとして確定する | インテグレーションを編集とデバイスを作成 |
| インテグレーションを削除する | インテグレーションを削除 |
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サンプルからデバイスを作成を開き、サンプルを取得して、提案されたフィールドを確定します。これでデバイスが作成されます。以降の手動のサンプルも同じエンドポイントを使います。定期的にプルするには、上で説明したとおり、行の設定を編集で同期間隔を設定します。
トラブルシューティング
以下の各メッセージは、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オブジェクトで入力します。ヘッダーとして送信されるのは、文字列と数値の値だけです。 |
| 保存された認証情報 | 保存時に暗号化され、書き込み専用で、保存後に返されることはありません。秘密鍵とパスフレーズは、返されることも、チャットに渡されることもありません。 |