概要

本ガイドは、次のことを可能にする Web SDK の情報を提供します。

• Things Cloud にデプロイできる Web アプリケーションを開発する
• 当社の API と認証された通信を行う
• カスタムアプリケーションにデフォルトまたはブランド UI コンポーネントを適用する

Web SDK はいつ使用できますか？

Web SDKは、デフォルトのアプリケーションを拡張するか、新しい IoT ソリューションを構築するために設計されています。このようなアプリケーションを構成するために、多くのデフォルトコンポーネントを提供します。ただし、当社のデフォルト アプリケーションのいずれかが、すでにあなたのユースケースに適している場合、そのアプローチを使って拡張し、プラグインをインストールすることを検討してください。特別なニーズが非常にある場合や、あなたのユースケースに適したプラグインが見つからない場合は、Web SDK を使用してカスタム アプリケーションを構築することを検討してください。基本的に、次の 3 つの選択肢があります。

1. 既存のアプリケーションを拡張する
2. Web SDK を使用して新しいアプリケーションを構築する
3. ゼロからアプリケーションを構築する

3 番目の選択肢は、ほぼすべてを新しく構築する必要があるため、最も難しい選択肢です。ただし、フレームワークやツールを自由に選択できます。どちらのオプションでもご利用いただけるよう、特定のパッケージをnpmに開発し、公開しました。これらのパッケージは、データへの接続、デフォルトコンポーネントの提供、アプリのテストとデプロイに役立ちます。必要に応じて、どのパッケージを含めるか選択できます。ただし、まずはボイラープレートと完全な Web SDK から始めることをお勧めしています。これらの使用方法については、はじめに ガイドをご覧ください。

パッケージ

Web SDK は @c8y というスコープで npm に公開され、Apache 2.0 ライセンスの下で利用可能な次のパッケージから構成されています。

これらのパッケージは、上から下へ依存しています。@c8y/client は非常に低レベルの API インターフェースで、ほとんど依存関係がありませんが、@c8y/<<apps>>（例：@c8y/cockpit）は、@c8y/ngx-components と @c8y/client を含むことによって、機能豊富なアプリケーションを提供します。

このように分割している目的は、すべてのユースケースに対して適切なパッケージを提供するためです。例えば、React で規模の小さなアプリケーションを構築したい場合、APIの疎通に @c8y/client を使用できます。コックピットやデバイス管理アプリケーションに近いブランディング可能な機能豊富なアプリケーションが必要な場合は、@c8y/styles と一緒に @c8y/ngx-components を使用できます。

次は、各パッケージのユースケースの一覧です。

• @c8y/client：このクライアントを使用して API にアクセスします。@c8y/client はアイソモーフィック（Isomorphic）であり、node.jsとブラウザの双方で使用できます。
• @c8y/ngx-components：Angular アプリケーションのためのコンポーネントのコレクションかつデータアクセス用のレイヤです。このパッケージは Angular アプリケーションを構築するのに使用されます。
• @c8y/style：アプリケーションの見た目用のスタイルパッケージです。アプリケーションにカスタムブランディングを適用するには、このパッケージを拡張してください。
• @c8y/<<apps>>：さまざまなアプリケーション。
  例：@c8y/cockpit、@c8y/devicemanagement、@c8y/administration
• @c8y/websdk：Angular アプリケーションに Things Cloud アプリケーションを追加するために使用できるスキャフォールディングパッケージです。
• @c8y/devkit：開発サーバーを構築または実行するためのビルダーです。

@c8y/client： データへのアクセス

@c8y/client は、Things Cloud REST API のためのアイソモーフィック（nodeおよびブラウザ）JavaScript クライアントライブラリです。これは、プラットフォームからデータを取得するために使用できます。Angular アプリケーションでは、主に @c8y/ngx-components の注入されたサービスを使用します。

@c8y/ngx-components： コンポーネントライブラリ

ngx-componentsは、Angular アプリケーション向けのコンポーネントコレクションおよびデータアクセスレイヤです。Angular アプリケーション内からプラットフォームにアクセスし、コアコンポーネントを提供することができます。これを実現するために、ngx-components は 2 つの基本的なインポートで構成されています。

• core（@c8y/ngx-components）： タイトル、ナビゲータ、タブなどのすべてのコアコンポーネントが含まれています。
• api（@c8y/ngx-components/api）： @c8y/client サービスへの依存性注入を可能にします。
• features（@c8y/ngx-components/<<feature-name>>）： アプリケーションに機能を追加する機能のセット

@c8y/style: ブランディングとテーマ

すべてのアプリケーションの外観を一括で変更するために、組み込みのブランディング エディタを使用することをお勧めします。特定のスタイルオプションを変更したい場合は、@c8y/style パッケージに .less ベースのスタイルがすべて含まれています。このスタイルを拡張して、独自のカスタムテーマを作成することができます。

@c8y/<<apps>>： 拡張可能なアプリケーション

次の表は、現在存在するアプリケーション用パッケージの概要を示しています。これらのアプリケーションのいずれかから、新しいアプリケーションをスキャフォールディングし、変更または拡張することができます。

ビルドツール：@c8y/websdk と @c8y/devkit

アプリケーションのスキャフォールディング（@c8y/websdk）と開発（@c8y/devkit）を支援する 2 つのビルドツールが追加されました。パッケージ @c8y/websdk は非常にシンプルで、新しいアプリケーションを作成するためのプロンプトのみを提供します。全体的な処理は @c8y/devkit によって行われます。angular.json 内のデフォルトの開発サーバーとビルダー オプションを置き換え、すべての必要な webpack 構成を拡張します。

バージョン管理：Web SDK はセマンティック バージョン番号を使用する

バージョン 1019.0.0 以降、Web SDK のバージョン管理スキーマは Things Cloud プラットフォームのバージョン管理スキーマと一致しなくなりました。バージョン管理スキーマは、Web SDK の変更をセマンティックバージョン管理で反映するようになりました。

• メジャーバージョン（例：1019.x.x）： メジャーバージョン (例: 1019.x.x): 互換性に影響する変更が含まれる場合があります。このようなバージョンに更新するには、適切なテストと検証が必要です。多くの場合、これらのバージョンには Angular のアップグレードも含まれています。
• マイナーバージョン（例：x.3.x）： 互換性に影響のない機能が含まれています。ただし、マイナーバージョンに含まれる機能については、適切に検証することをお勧めします。
• 修正バージョン（例：x.x.7）： 互換性に影響のない修正のみが含まれています。

すべての @c8y ライブラリに対して、package.json で ^ または ~ を使用することをお勧めします。年間長期サポートリリースを使用する場合は、package.json で npm タグを使用するのが最適です。長期サポートバージョンは常に -lts で終わります。

リリースは Angular のバージョン番号にバインドされているため、正しい Angular バージョンをスキャフォールディングする必要があります。そうでない場合、スキャフォールディング プロセスは失敗し、ピア依存関係エラーが発生します。次の表は、サポートされているバージョンの概要を示しています。

次のステップ

これから使い始める方は、はじめに をお読みいただくことをお勧めします。この章では、Web SDK ベースの Angular アプリケーションを初めてセットアップする方法を説明しています。すでにアプリケーションをセットアップ済みで、コンセプトの詳細を理解したい場合は、Codex 開発者向け ドキュメントを参照してください。このドキュメントでは、コンセプトの説明、すべてのコンポーネントのリスト、スタイル設定のガイドラインが定義されています。