diff options
Diffstat (limited to 'platformdoc/docs/components/component-specification/dmaap-connection-objects.md')
| -rw-r--r-- | platformdoc/docs/components/component-specification/dmaap-connection-objects.md | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/platformdoc/docs/components/component-specification/dmaap-connection-objects.md b/platformdoc/docs/components/component-specification/dmaap-connection-objects.md new file mode 100644 index 00000000..b1b650fd --- /dev/null +++ b/platformdoc/docs/components/component-specification/dmaap-connection-objects.md @@ -0,0 +1,169 @@ +# DMaaP connection objects + +DMaaP Connection Objects are JSON objects that: + +1. At Runtime - this is generated by the DCAE Platform and passed to the component in its application_configuration to be used to connect to the DMaaP feed or topic. Components will receive the entire object with all properties populated (default will be `null) unless specified otherwise. +2. During dcae_cli testing - this is provided through the command-line argument `--dmaap-file` to test the component with manually provisioned feeds and topics. Developers are not required to provide the entire object. The required properties are labeled below with "*Required as input*". + +## Message Router + +Publishers and subscribers have the same generated `Dmaap Connection Object` structure. Here's an example for any given config-key: +(This is what will be in application_configuration) + +```json +{ + "type": "message_router", + "aaf_username": "some-user", + "aaf_password": "some-password", + "dmaap_info": { + "client_role": "com.dcae.member", + "client_id": "1500462518108", + "location": "mtc00", + "topic_url": "https://we-are-message-router.us:3905/events/some-topic" + } +} +``` + +At the top-level: + +Property Name | Type | Description +------------- | ---- | ----------- +type | string | *Required as input*. Must be `message_router` for message router topics +aaf_username | string | AAF username message router clients use to authenticate with secure topics +aaf_password | string | AAF password message router clients use to authenticate with secure topics +dmaap_info | JSON object | *Required as input*. Contains the topic connection details + +The `dmaap_info` object contains: + +Property Name | Type | Description +------------- | ---- | ----------- +client_role | string | AAF client role that's requesting publish or subscribe access to the topic +client_id | string | Client id for given AAF client +location | string | DCAE location for the publisher or subscriber, used to set up routing +topic_url | string | *Required as input*. URL for accessing the topic to publish or receive events + +The --dmaap-file argument (to the component `run` or `dev` command), must minimally contain: + +```json +{ + "type": "message_router", + "dmaap_info": { + "topic_url": "https://we-are-message-router.us:3905/events/some-topic" + } +} +``` + +## Data Router + +### Publisher + +Here's an example of what the generated `Dmaap Connection Object` for Data Router Publisher looks like: +(This is what will be in application_configuration) + +```json +{ + "type": "data_router", + "dmaap_info": { + "location": "mtc00", + "publish_url": "https://we-are-data-router.us/feed/xyz", + "log_url": "https://we-are-data-router.us/feed/xyz/logs", + "username": "some-user", + "password": "some-password", + "publisher_id": "123456" + } +} +``` + +At the top-level: + +Property Name | Type | Description +------------- | ---- | ----------- +type | string | *Required as input*. Must be `data_router` for data router feeds +dmaap_info | JSON object | *Required as input*. Contains the feed connection details + +The `dmaap_info` object contains: + +Property Name | Type | Description +------------- | ---- | ----------- +location | string | DCAE location for the publisher, used to set up routing +publish_url | string | *Required as input*. URL to which the publisher makes Data Router publish requests +log_url | string | URL from which log data for the feed can be obtained +username | string | Username the publisher uses to authenticate to Data Router +password | string | Password the publisher uses to authenticate to Data Router +publisher_id | string | Publisher id in Data Router + +The --dmaap-file argument (to the component `run` or `dev` command), must minimally contain: + +```json +{ + "type": "data_router", + "dmaap_info": { + "publish_url": "https://we-are-data-router.us/feed/xyz" + } +} +``` + +### Subscriber + +Here's an example of what the generated `Dmaap Connection Object` for a Data Router Subscriber looks like: +(This is what will be passed in application_configuration) + +```json +{ + "type": "data_router", + "dmaap_info": { + "location": "mtc00", + "delivery_url": "https://my-subscriber-app.dcae:8080/target-path", + "username": "some-user", + "password": "some-password", + "subscriber_id": "789012" + } +} +``` + +At the top-level: + +Property Name | Type | Description +------------- | ---- | ----------- +type | string | *Required as input*. Must be `data_router` for data router feeds +dmaap_info | JSON object | *Required as input*. Contains the feed connection details + +The `dmaap_info` object contains: + +Property Name | Type | Description +------------- | ---- | ----------- +location | string | DCAE location for the subscriber, used to set up routing +delivery_url | string | URL to which the Data Router should deliver files +username | string | Username Data Router uses to authenticate to the subscriber when delivering files +password | string | Password Data Router uses to authenticate to the subscriber when delivering files +subscriber_id | string | Subscriber id in Data Router + +The --dmaap-file argument (to the component `run` or `dev` command), must minimally contain: + +```json +{ + "type": "data_router", + "dmaap_info": { + } +} +``` + +It is the recommended security practice that `username` and `password` are specified. +You cannot provide the `delivery_url` in your dmaap-file, because it's not constructed until deployment time. Therefore, after the test deployment, go back to the Data Router Feed and provide the delivery_url (in order to start receiving the feeds). + +### Data Router Example + +(After the Data Router feed has been manually provisioned) + +``` +$ dcae_cli component run --dmaap-file $dmaap_file $component-name +DCAE.Run | WARNING | Your component is a data router subscriber. Here are the delivery urls: + + some-sub-dr: http://135.205.226.128:32838/identity +``` + +(Update the Data Router Feed to provide the delivery_url). + + + + |