アプリケーション

概要

下記のAPIは「/platform」では公開されていませんが、「/application」を利用することにより利用することができます。

アプリケーションインターフェースは以下の要素で構成されます。

  • 「アプリケーションAPI」リソースは、すべてのアプリケーション、特定の名称のすべてのアプリケーションおよび特定のテナントが所有するすべてのアプリケーションのクエリが可能となるよう、アプリケーションコレクションにURIおよびURIテンプレートを返します。
  • 「アプリケーションコレクション」リソースは一連のアプリケーションを読み出し、新規アプリケーションの作成を可能にします。
  • 「アプリケーション」リソースは、クエリおよび削除が可能な個々のアプリケーションを表わします。
  • 「アプリケーションブートストラップユーザー」リソースはマイクロサーバーユーザーのブートストラップの資格情報を取得します。
  • 「アプリケーションユーザー」リソースとは単一のサブクリプションエントリを表します。
  • 「現在のアプリケーションサブクリプション」は現在のアプリケーションサブクリプションへアクセスするエンドポイントを提供します。
  • 「アプリケーションバイナリ」は展開できる アプリケーションをプラットフォーム上へアップロードする為のエンドポイントを提供します。

注記:すべてのPUT/POSTリクエストについて、acceptヘッダーを使用すべきであり、さもなければ空の応答本体が返されます。

アプリケーションの名称

Things Cloudは各テナントの使用可能なアプリケーションを管理します。 Things Cloudは多種多様なアプリケーションを提供しています。

利用可能なアプリケーションは下記の表に記載されています。項目の詳細は以下の通りです:

  • アプリケーション: アドミニストレーションアプリケーションで表示されているアプリケーションの名前です。
  • 機能性:簡単な説明になります。
  • 文字列: API上でのアプリケーションの識別名。APIを使用してアプリケーションにテナントを申請したい場合(このページで説明された通り)引数nameとしてこの文字列を使用してください。
  • 可用性: 「スタンダード・エディション」と表されたアプリは全て使用可能です。「オプション・サービス」となるものは Things Cloud のインスタンス用に関連のお申込みが必要となります。
アプリケーション 機能 文字列 可用性
アドミニストレーション アカウント管理者によるユーザー、ロール、テナント、およびアプリケーションの管理を可能にします。 administration スタンダード・エディション
Cep Esper CEPエンジンを使用して、リアルタイムデータに基づいてビジネスオペレーションを定義します。 cep スタンダード・エディション
CEP カスタムルール Esperで作成した独自のCEPルールをアップロードし、テナントごとの展開します。 feature-cep-custom-rules オプションサービス
コックピット ビジネスの観点からIoTのアセットとデータを管理および監視できます。 cockpit スタンダード・エディション
クラウド Fieldbus fieldbus デバイスからデータを収集し、それらをThings Cloudでリモート管理します。 feature-fieldbus4 オプションサービス
デバイス管理 デバイスを管理および監視し、デバイスをリモートで制御および修理します。 devicemanagement スタンダード・エディション
デバイス・シミュレーター IoTデバイスのあらゆる側面をシミュレートします。 device-simulator スタンダード・エディション
LoRa Actility ActilityのThingPark Wirelessを介してLoRaデバイスとインターフェースします。この機能を利用するには別途お申し込みが必要です。 actility オプションサービス
Sigfox Sigfox エージェント を使用し、Sigfox クラウド経由で Sigfoxデバイスをインターフェースできます。この機能を利用するには別途お申し込みが必要です。 sigfox-agent オプションサービス
スマートルール スマートルールエンジンを使用して、リアルタイムデータに基づいたアクションを実行する スマートルール を作成します。 smartrule スタンダード・エディション

アプリケーションAPI

ApplicationAPI [application/vnd.com.nsn.cumulocity.applicationApi+json]

名称 種別 発生回数 説明
self URL 1 このリソースへのリンク
applicationById Application/URI-Template 1 種別がアプリケーションであるリソースに対するリファレンス(プレースホルダ:{id})
applications ApplicationCollection 1 すべてのアプリケーションのコレクション
applicationsByName ApplicationCollection URI-Template 1 特定の名称を有するアプリケーションすべてから成る読み取り専用コレクション(プレースホルダ:{name})。
applicationsByTenant ApplicationCollection URI-Template 1 特定のテナントがチャネル接続しているアプリケーションすべてから成る読み取り専用コレクション(プレースホルダ:{tenant})。
applicationsByOwner ApplicationCollection URI-Template 1 特定のテナントが所有しているアプリケーションすべてから成る読み取り専用コレクション(プレースホルダ:{tenant})。

アプリケーションAPIリソースをGETする

応答本体:アプリケーションAPI

要求されるロール: ROLE_APPLICATION_READ

リクエスト例:

GET /application
Host: ...
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.ApplicationApi+json;ver=...
Content-Length: ...
{
    "self" : "<<ApplicationAPI URL>>",
    "applicationsByID" : "<<ApplicationCollection URL>>/{id}",
    "applications" : "<<ApplicationCollection URL>>",
    "applicationsByName" : "<<ApplicationAPI URL>>/applicationByName/{name}",
    "applicationsByOwner" : "<<ApplicationAPI URL>>/applicationsByOwner/{tenantName}",
    "applicationsByTenant" : "<<ApplicationAPI URL>>/applicationsByTenant/{tenantName}"
}

アプリケーションコレクション

ApplicationCollection [application/vnd.com.nsn.cumulocity.applicationCollection+json]

名称 種別 発生回数 説明
self URI 1 このリソースへのリンク
applications Application 0..n アプリケーションのリスト(下記参照)
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 アプリケーションの潜在的な前のページへのリンク
next URI 0..1 アプリケーションの潜在的な次のページへのリンク

アプリケーションコレクションをGETする

応答本体:アプリケーションコレクション

要求されるロール: ROLE_APPLICATION_MANAGEMENT_READ

リクエスト例:

GET /application/applications
Host: ...
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationCollection+json;ver=...
Content-Length: ...
{
    "self" : "...",
    "next" : "...",
    "prev" : "...",
    "applications": [
        {
            "availability": "PRIVATE",
            "id": "101",
            "key": "...",
            "name": "myOwnApplcation",
            "owner": {
                "self": "...",
                "tenant": {
                    "id": "test"
                }
            },
            "self": "...",
            "type": "HOSTED",
            "contextPath": "/my_own_application",
            "resourcesUrl":"...",
            "resourcesUsername": "...",
            "resourcesPassword": "..."
        },
        {
            "availability": "MARKET",
            "id": "3",
            "key": "...",
            "name": "energyapp",
            "owner": {
                "self": "...",
                "tenant": {
                    "id": "management"
                }
            },
            "self": "...",
            "type": "EXTERNAL",
            "externalUrl": "..."

        }
    ],
    "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 1
    }
}

POST - 新規アプリケーションを作成する

リクエスト本体:アプリケーション

応答本体:アプリケーション

要求されるロール: ROLE_APPLICATION_MANAGEMENT_ADMIN.

リクエスト例:

POST /application/applications
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...

{
  "key": "vehicleControlApplicationSecretKey",
  "name": "vehicleControlApplication",
  "type": "HOSTED",
  "contextPath": "/vehicleControlApplication",
  "resourcesUrl":"http://external.host.com/basedir"
}

応答例:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
Location: <<URL of new application>>

{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiCorp"
      }
  },
  "self": "...",
  "type": "HOSTED",
  "contextPath": "/vehicleControlApplication",
  "resourceUrl":"http://external.host.com/basedir",
  "resourcesUsername": "..."
}

アプリケーション

Application [application/vnd.com.nsn.cumulocity.application+json;ver=0.9]

フィールド名 種別 発生回数 説明 PUT/POST
self URL 1 このリソースへのリンク いいえ
id String 1 アプリケーションの固有識別子 いいえ
name String 1 アプリケーション名 POST:必須、PUT:任意
key String 1 アプリケーションの共有秘密鍵 POST:必須、PUT:任意
type String 1 アプリケーションの種別。可能な値:EXTERNAL、HOSTED、MICROSERVICE、APAMA_CEP_RULE POST:必須、PUT:非必須
availability String 0..1 他のテナントからのアクセスレベル。可能な値:MARKET、PRIVATE(デフォルト) 任意
owner TenantReference ?1 このアプリケーションを所有しているテナントに対するリファレンス いいえ
contextPath String 0..1 ホスト型アプリケーションのコンテキストパス POST:必須(HOSTEDの場合)、PUT:任意
resourcesUrl String 0..1 外部サーバー上でホストされるアプリケーションベースディレクトリへのURL POST:必須(HOSTEDの場合)、PUT:任意
resourcesUsername String 0..1 リソースURLにアクセスするための認可ユーザー名 任意
resourcesPassword String 0..1 リソースURLにアクセスするための認可パスワード 任意
externalUrl String 0..1 外部アプリケーションへのURL POST:必須(EXTERNALの場合)、PUT:任意

POST - アプリケーションを複製する

「クローン」リソースに対するPOSTリクエストは、既存のアプリケーションをベースとするアプリケーションを新たに作成します。 プロパティは新たに作成されるアプリケーションへコピーされます。 名称、キーおよびコンテキストパスについては、一意にするための「clone」プレフィックスが追加されます。 対象アプリケーションがホスト型で、有効なバージョンを有する場合、新規アプリケーションも同じ内容の有効バージョンを有することになります。 応答は新たに作成されたアプリケーションの表現を格納します。

要求されるロール: ROLE_APPLICATION_MANAGMENT_ADMIN

リクエスト例:

POST /application/applications/<<application_id>>/clone HTTP/1.1
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.application+json

応答例:

HTTP/1.1 201 Created
Location: .../application/applications/{{application_id}}
Content-Type: application/vnd.com.nsn.cumulocity.application+json; charset=UTF-8; ver=0.9
{
    "activeVersionId": "10414",
    "availability": "MARKET",
    "contextPath": "clonetest",
    "id": "1115",
    "key": "clonesecretKeyForTheApplication",
    "manifest": {},
    "name": "clonetestApplicationName",
    "owner": {
        "self": ".../tenant/tenants/management",
        "tenant": {
            "id": "management"
        }
    },
    "resourcesUrl": "/test",
    "self": ".../application/applications/1115",
    "type": "HOSTED"
}

PUT - アプリケーションを更新する

リクエスト本体:アプリケーション

応答本体:アプリケーション(「ACCEPT」ヘッダーを指定された場合)

要求されるロール: ROLE_APPLICATION_MANAGMENT_ADMIN

リクエスト例:

PUT /application/applications/<<applicationId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
{
  "availability" : "MARKET"
}

アプリケーションをGETする

応答本体:アプリケーション

要求されるロール: ROLE_APPLICATION_MANAGEMENT_READ

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiDrive"
      }
  },
  "self": "...",
  "type": "EXTERNAL",
  "externalUrl":"http://external.host.com/application"
}

アプリケーションをDELETEする

リクエスト本体:N/A

応答本体:N/A

要求されるロール: ROLE_APPLICATION_MANAGMENT_ADMIN と OWNER

注記:アプリケーションは可用性がPRIVATEであるか、そうでない場合はチャネル接続が存在しない状況でないと削除できません。

リクエスト例:アプリケーションをDELETEする

DELETE /application/applications/<<applicationId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

Bootstrap ユーザー

bootstrap ユーザーを GET する

応答本体: ApplicationUser

要求されるロール: ROLE_APPLICATION_MANAGEMENT_ADMIN

リクエスト例:

GET
application/applications/{microservice-applicationId}/bootstrapUser
Host: ...
Authorization: Basic ....
Accept: application/vnd.com.nsn.cumulocity.user+json;ver=...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=...
Content-Length: ...
{
    "name": "servicebootstrap_hello-world",
    "password": "9HqBc0miL5",
    "tenant": "dariusz"
}

Current application

現在のアプリケーションを GET する。

応答本体: アプリケーション

bootstrapユーザーによる必要な認証

リクエスト例:

GET /application/currentApplication
Host: ...
Authorization: Basic .....
Accept: application/vnd.com.nsn.cumulocity.application+json;ver=...

応答例:

HTTP/1.1 200 OK
Content-Type:
application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiDrive"
      }
  },
  "self": "...",
  "type": "MICROSERVICE",
  "externalUrl":"http://external.host.com/application"
}

PUT - 現在のアプリケーションのアップデート

応答本体: アプリケーション

bootstrapユーザーによる必要な認証

リクエスト例:

PUT /application/currentApplication
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.application+json;ver=...
{
      "availability": "PRIVATE",
      "id": "105",
      "key": "...",
      "name": "vehicleControlApplication",
      "owner": {
          "self": "...",
          "tenant": {
              "id": "taxiDrive"
          }
      },
      "self": "...",
      "type": "MICROSERVICE",
      "externalUrl":"http://external.host.com/application"
    }

応答例:

HTTP/1.1 200 OK
Content-Type:
application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "...",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "..."
      }
  },
  "self": "...",
  "type": "MICROSERVICE"
}

ApplicationSubscriptionCollection

ApplicationSubscriptionCollection[application/vnd.com.nsn.cumulocity.applicationUserCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
users ApplicationUser 0..n サブスクリプションしているユーザー一覧。下記参照
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 アプリケーションの前のページへのリンク(あれば)
next URI 0..1 アプリケーションの次のページへのリンク(あれば)

ApplicationUser

フィールド名 タイプ 発生回数 説明
tenant String 1 サブスクリプションされたテナント
name String 1 ユーザー名
password String 1 パスワード

現在のアプリケーションのサブスクリプションを GET する

応答本体: ApplicationSubscriptionCollection

Required authentication with bootstrap user

リクエスト例:

GET /application/currentApplication/subscriptions
Host: ...
Authorization: Basic ....
Accept: application/vnd.com.nsn.cumulocity.applicationUserCollection+json;ver=...

応答例:

HTTP/1.1 200 OK
Content-Type: 
application/vnd.com.nsn.cumulocity.applicationUserCollection+json;
ver=...
Content-Length: ...
{
    "users": [
        {
            "name": "service_hello-world",
            "password": "...",
            "tenant": "..."
        }
    ]
}

アプリケーション・バイナリ

POST - アプリケーションバイナリのアップロード

アプリケーションを Things Cloud プラットフォームのユーザーが使用できるようにするには、バイナリのzipファイルをアップロードする必要があります。 POST /application/applications/{APPLICATION_ID}/binaries Host: ... Authorization: Basic … Content-Type: multipart/form-data

Webアプリケーションの場合、zipファイルのルートディレクトリに index.html が含まれている必要があります。

HTTP/1.1  204 NO CONTENT