トピック・ポリシーの作成または更新

目的

URI

以下の IBM® IoT MessageSight 構成 URI を使用して、IBM IoT MessageSight REST API POST メソッドを使用します。

http://<admin-endpoint-IP:Port>/ima/v1/configuration/

オブジェクト構成データ

以下のスキーマを使用して、POST メソッドのペイロードに TopicPolicy オブジェクト構成データを指定します。Content-type は application/json に設定されます。

{    
   "TopicPolicy": {
     "<NameOfTopicPolicy>": {
       "Description": "string",
       "Topic": "string",
       "ActionList": "string",
       "MaxMessages": integer,
       "MaxMessagesBehavior": "RejectNewMessages"|"DiscardOldMessages",
       "MaxMessageTimeToLive": "string",
       "DisconnectedClientNotification": true|false,
       "ClientID": "string",
       "UserID": "string",
       "GroupID": "string",
       "CommonNames": "string",
       "ClientAddress": "string",
       "Protocol": "string"             
    }
  }
}

NameOfTopicPolicy

必須。

トピック・ポリシーの名前を指定します。

名前の先頭と末尾にはスペースがあってはなりません。また、名前には、制御文字、コンマ、二重引用符、円記号、または等号は使用できません。先頭文字は、数字または次のいずれかの特殊文字であってはなりません。: ! # $ % & ' ( ) * + - . / : ; < > ? @

トピック・ポリシーの作成後は、この名前は変更できません。

Description

オプション。

トピック・ポリシーの説明を指定します。

説明が不要な場合は、"Description": "description" を省きます。

Topic

トピック・ポリシーを作成している場合は必須です。

トピック・ポリシーを適用するトピック・ストリングを指定します。

アスタリスク (*) をワイルドカードとして使用できます。例えば、トピック・ストリング TOPICA/# にトピック・ポリシーを適用するには、トピッ クを TOPICA/* と入力します。ワイルドカードを使用するときは、意図した以上の権限をトピックに付与しないよう注意してください。ワイルドカード文字の使用方法について詳しくは、ワイルドカードを参照してください。

ドル記号 ($) とアスタリスク (*) は、トピック・フィールドでは特別な意味を持ちます。これらの文字をリテラルとして使用する場合は、ドル記号には ${$} を、アスタリスクには ${*} を使用します。

トピック・ストリングで変数置換を使用して、特定のユーザー ID、グループ ID、クライアント ID、またはクライアント証明書共通名を持つクライアントのみがトピックにアクセスできるようにします。変数は、以下のとおりです。

• ユーザー ID は、${UserID}。
• グループ ID は、${GroupID}。
• クライアント ID は、${ClientID}。
• クライアント証明書共通名は、${CommonName}。

例えば、トピック・ポリシー内のトピック・ストリングが ExampleTopic/TopicA/${ClientID} である場合、client_a の ID を持つクライアントはトピック ExampleTopic/TopicA/client_a にアクセスすることができます。client_b の ID を持つクライアントは、トピック ExampleTopic/TopicA/client_a にアクセスできませんが、ExampleTopic/TopicA/client_b にアクセスできます。

ActionList

トピック・ポリシーを作成している場合は必須です。

このトピック・ポリシーに関連付けられているエンドポイントに接続するクライアントが使用できるメッセージング・アクションを指定します。

トピック・ポリシーに対して、以下の値を指定できます。複数を指定する場合は、それぞれの値をコンマで区切ります。

• Publish

  トピック・ポリシーに指定されたトピックに、クライアントがパブリッシュできるようにします。

• Subscribe

  トピック・ポリシーに指定されたトピックに、クライアントがサブスクライブできるようにします。

MaxMessages

オプション。

サブスクリプションに対して保持するメッセージの最大数を指定します。 この値は、絶対的な制限ではなく指標です。システムが負荷のかかる状態で稼働している場合、サブスクリプションのバッファーに入れられたメッセージの数は、MaxMessages 値よりも若干多い場合があります。

デフォルト値は 5000 です。

MaxMessagesBehavior

オプション。

サブスクリプションのバッファー内のメッセージの数が、最大値に達したときに適用される動作を指定します。つまり、サブスクリプションのバッファーが満杯のときの動作です。動作は、永続的サブスクリプションと非永続的サブスクリプションの両方に適用されます。

動作には、以下のいずれかのオプションを指定できます。

• RejectNewMessages

  サブスクリプションのバッファーで新規のメッセージを受け入れません。

• DiscardOldMessages

  サブスクリプションのバッファーにある特定の割合の古いメッセージを破棄します。保存されたメッセージが古いメッセージの 1 つである場合、そのメッセージは破棄されます。メッセージは、そのサービス品質、永続性、優先度にかかわらず破棄されます。したがって、アプリケーションが正しく機能するためにすべてのメッセージを受信する必要がある場合、MaxMessagesBehavior を DiscardOldMessages に設定することはできません。

デフォルトの動作は RejectNewMessages です。

MaxMessageTimeToLive

オプション。

トピック・ポリシーに関連付けられているパブリッシュ済みメッセージが IBM IoT MessageSight 内に存在できる最大時間を秒数で指定します。

値は unlimited、または 1 から 2147483647 までの範囲内である必要があります。

デフォルト値は unlimited です。これは、パブリッシュ側アプリケーションによってメッセージの存続時間が指定されない限り、メッセージの有効期限が切れないことを意味します。

この値は、トピック・ポリシーにパブリッシュ・アクションが含まれる 場合にのみ適用されます。

有効期限が切れたメッセージを受信する可能性を最小限にするために、クライアントとサーバーの時刻が同期していることを確認してください。

DisconnectedClientNotification: true|false

オプション。

メッセージの到着時に、接続されていない MQTT クライアントに対して通知メッセージを発行するかどうかを指定します。

デフォルト値は false です。

この値は、MQTT プロトコルが使用されている場合にのみ適用されます。

通知メッセージは、予約済みのシステム・トピック $SYS/DisconnectedClientNotification に対して発行されます。

以下のフィルターの少なくとも 1 つを指定する必要があります。

ClientID

トピック・ポリシーに指定されたメッセージング・アクションの使用を許可されるクライアント ID を指定します。クライアント ID は、ポリシーに指定されているトピックでのみ、メッセージング・アクションを使用することが許可されます。

アスタリスク (*) を値の最後に使用して、0 文字以上の一致候補を表せます。

デフォルト値 (すべてのクライアント ID 値がアクションを使用することを許可する) を使用するには、 "ClientID":"ClientID" を省きます。

UserID

トピック・ポリシーに指定されたメッセージング・アクションの使用を許可されるメッセージング・ユーザー ID を指定します。メッセージング・ユーザー ID は、ポリシーに指定されているトピックでのみ、メッセージング・アクションを使用することが許可されます。

アスタリスク (*) を値の最後に使用して、0 文字以上の一致候補を表せます。

デフォルト値 (すべてのユーザー ID 値がアクションを使用することを許可する) を使用するには、"UserID": "UserID" を省きます。

GroupID

トピック・ポリシーに指定されたメッセージング・アクションの使用を許可されるメッセージング・グループを指定します。メッセージング・グループは、ポリシーに指定されているトピックでのみ、メッセージング・アクションを使用することが許可されます。

アスタリスク (*) を値の最後に使用して、0 文字以上の一致候補を表せます。

デフォルト値 (すべてのグループがアクションを使用することを許可する) を使用するには、"GroupID": "GroupID" を省きます。

CommonNames

トピック・ポリシーに指定されたアクションの使用をクライアントに許可するために使用する必要のある、クライアント証明書共通名を指定します。 クライアント証明書共通名は、ポリシーに指定されているトピックでのみメ ッセージング・アクションの使用をクライアントに許可します。

アスタリスク (*) を値の最後に使用して、0 文字以上の一致候補を表せます。

デフォルト値 (すべてのクライアント証明書がアクションを使用することを許可する) を使用するには、"CommonNames": "CommonNames" を省きます。

ClientAddress

トピック・ポリシーに指定されたメッセージング・アクションの使用を許可される IP アドレスを指定します。クライアント IP アドレスは、ポリシーに指定されているトピックでのみメッセージング・ アクションを使用することが許可されます。

IP アドレスは、アスタリスク (*) を使用して指定できます。あるいは、IPv4 アドレスや IPv6 アドレス、または IP アドレスの範囲をコンマで区切ったリストとして指定できます。例えば、192.0.2.32, 192.0.0.0, 192.0.2.0-192.0.2.100 などです。範囲は、低い値から高い値へと指定する必要があります。

しかし、単独で表記される場合もアドレスの範囲として表記される場合も、各 IPv6 アドレスは大括弧 [ ] で囲む必要があります。IPv6 アドレスに アスタリスクを含めることはできません。

指定できるクライアント・アドレスの最大数は 20 です。

デフォルト値 (すべてのクライアント IP アドレスが接続を許可されている) を使用する場合は、 "ClientAddress":"IP_Address" を省くか、または "ClientAddress":"*" を指定します。

Protocol

ポリシーに指定されているトピックで、トピック・ポリシーに指定されるアクションの使用を許可されるプロトコルを指定します。

JMS と MQTT の各プロトコルから選択できます。IBM IoT MessageSight サーバー上にプロトコル・プラグインがインストールされている場合は、それらも指定できます。複数の値を指定する場合は、それぞれの値をコンマで区切ります。すべてのプロトコルを選択するには、プロトコルに NULL 値を指定するか、コマンドから パラメーターを省きます。

使用上の注意

• 大/小文字の区別および二重引用符は、以下に示すとおりに使用されている必要があります。
• 各フィルター (ClientAddress、ClientID、UserID、GroupID、CommonNames、および Protocols) は組み合わせて適用されます。 複数のフィルターを指定する場合、メッセージング・ポリシーに指定されるアクションを許可するには、各条件が満たされている必要があります。 指定していない各フィルターでは、そのフィルターのすべての値が許可されます。

  例えば、 "ActionList": "Publish" "GroupID": "SILVER" "ClientID": "SIL*" "Protocol": "JMS" のように指定するトピッ ク・ポリシーを作成するとします。JMS を使用する、グループ SILVER のユーザー ID SIL1 を持つクライアントはメッセージをパブリッシュできます。 JMS を使用する、グループ GOLD のユーザー ID SIL2 を持つクライアントは、すべてのフィルター条件が満たされているわけではないため、メッセージをパブリッシュできません。

関連する REST 管理 API

• メッセージング・ハブの作成または更新
• 接続ポリシーの作成または更新
• サブスクリプション・ポリシーの作成または更新
• キュー・ポリシーの作成または更新
• エンドポイントの作成または更新
• 命名可能な構成オブジェクトの構成の詳細表示
• 構成オブジェクトの削除

例

curl -X POST  \
   -H 'Content-Type: application/json'  \
   -d  '{                          
           "TopicPolicy": {   
               "MyTopicPolicy": {
                "Description": "Topic policy to authorize a client to publish to a topic.",
                "Topic": "*",
                "ClientID": "*",
                "ActionList": "Publish,Subscribe"
              }
          }
      }
 '   \
http://127.0.0.1:9089/ima/v1/configuration/

{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}