platformdoc/docs/components/dcae-cli/dmaap-connection-objects.md

   1 # DMaaP connection objects
   2
   3 DMaaP connection objects are JSON objects that:
   4
   5 1. Components should expect at runtime in their application configuration and is to be used to connect to the appropriate DMaaP feed or topic.
   6 2. Developers must provide through the command-line argument `--dmaap-file` to test their component with manually provisioned feeds and topics.
   7
   8 This page is a reference to the specific structure that each type of DMaaP stream requires.
   9
  10 Note for #1 that components should expect the entire object with all properties at runtime where the default will be `null` unless specified otherwise.
  11
  12 Note for #2 that developers are not required to provide the entire object.  The required properties will be labeled with "*required as input*".
  13
  14 ## Message router
  15
  16 Publishers and subscribers both have the same JSON object structure.  Here's an example:
  17
  18 ```json
  19 {
  20     "type": "message_router",
  21     "aaf_username": "some-user",
  22     "aaf_password": "some-password",
  23     "dmaap_info": {
  24         "client_role": "com.dcae.member",
  25         "client_id": "1500462518108",
  26         "location": "mtc00",
  27         "topic_url": "https://we-are-message-router.us:3905/events/some-topic"
  28     }
  29 }
  30 ```
  31
  32 At the top-level:
  33
  34 Property Name | Type | Description
  35 ------------- | ---- | -----------
  36 type | string | *Required as input*.  Must be `message_router` for message router topics
  37 aaf_username | string | AAF username message router clients use to authenticate with secure topics
  38 aaf_password | string | AAF password message router clients use to authenticate with secure topics
  39 dmaap_info | JSON object | *Required as input*. Contains the topic connection details
  40
  41 The `dmaap_info` object contains:
  42
  43 Property Name | Type | Description
  44 ------------- | ---- | -----------
  45 client_role | string | AAF client role that's requesting publish or subscribe access to the topic
  46 client_id | string | Client id for given AAF client
  47 location | string | DCAE location for the publisher or subscriber, used to set up routing
  48 topic_url | string | *Required as input*. URL for accessing the topic to publish or receive events
  49
  50 Here's an example of the minimal JSON that must be provided as an input:
  51
  52 ```json
  53 {
  54     "type": "message_router",
  55     "dmaap_info": {
  56         "topic_url": "https://we-are-message-router.us:3905/events/some-topic"
  57     }
  58 }
  59 ```
  60
  61 ## Data router
  62
  63 ### Publisher
  64
  65 Here's an example of what the JSON object connection for data router publisher looks like:
  66
  67 ```json
  68 {
  69     "type": "data_router",
  70     "dmaap_info": {
  71         "location": "mtc00",
  72         "publish_url": "https://we-are-data-router.us/feed/xyz",
  73         "log_url": "https://we-are-data-router.us/feed/xyz/logs",
  74         "username": "some-user",
  75         "password": "some-password",
  76         "publisher_id": "123456"
  77     }
  78 }
  79 ```
  80
  81 At the top-level:
  82
  83 Property Name | Type | Description
  84 ------------- | ---- | -----------
  85 type | string | *Required as input*.  Must be `data_router` for data router feeds
  86 dmaap_info | JSON object | *Required as input*. Contains the topic connection details
  87
  88 The `dmaap_info` object contains:
  89
  90 Property Name | Type | Description
  91 ------------- | ---- | -----------
  92 location | string | DCAE location for the publisher, used to set up routing
  93 publish_url | string | *Required as input*. URL to which the publisher makes Data Router publish requests
  94 log_url | string | URL from which log data for the feed can be obtained
  95 username | string | Username the publisher uses to authenticate to Data Router
  96 password | string | Password the publisher uses to authenticate to Data Router
  97 publisher_id | string | Publisher id in Data Router
  98
  99 Here's an example of the minimal JSON that must be provided as an input:
 100
 101 ```json
 102 {
 103     "type": "data_router",
 104     "dmaap_info": {
 105         "publish_url": "https://we-are-data-router.us/feed/xyz"
 106     }
 107 }
 108 ```
 109
 110 ### Subscriber
 111
 112 Here's an example of what the JSON object connection for data router subscriber looks like:
 113
 114 ```json
 115 {
 116     "type": "data_router",
 117     "dmaap_info": {
 118         "location": "mtc00",
 119         "delivery_url": "https://my-subscriber-app.dcae:8080/target-path",
 120         "username": "some-user",
 121         "password": "some-password",
 122         "subscriber_id": "789012"
 123     }
 124 }
 125 ```
 126
 127 At the top-level:
 128
 129 Property Name | Type | Description
 130 ------------- | ---- | -----------
 131 type | string | *Required as input*.  Must be `data_router` for data router feeds
 132 dmaap_info | JSON object | *Required as input*. Contains the topic connection details
 133
 134 The `dmaap_info` object contains:
 135
 136 Property Name | Type | Description
 137 ------------- | ---- | -----------
 138 location | string | DCAE location for the publisher, used to set up routing
 139 delivery_url | string | URL to which the Data Router should deliver files
 140 username | string | Username Data Router uses to authenticate to the subscriber when delivering files
 141 password | string | Password Data Router uses to authenticate to the subscriber when delivering files
 142 subscriber_id | string | Subscriber id in Data Router
 143
 144 Here's an example of the minimal JSON that must be provided as an input:
 145
 146 ```json
 147 {
 148     "type": "data_router",
 149     "dmaap_info": {
 150     }
 151 }
 152 ```
 153
 154 Developers are recommended to use `username` and `password` since this is the recommended security practice.
 155
 156 Note that the dcae-cli will construct the `delivery_url` when deploying the component since this can only be known at deployment time.