GooglePubSubAdapter Adapter

The GooglePubSubAdapter adapter provides the ability for the ClearBlade platform to communicate with a the PubSub functionality within the Google Cloud Platform.

MQTT Topic Structure

The GooglePubSubAdapter adapter utilizes MQTT messaging to communicate with the ClearBlade Platform. The GooglePubSubAdapter adapter will subscribe to a specific topic in order to handle requests from the ClearBlade Platform/Edge to publish data to Cloud Pub/Sub. Additionally, the GooglePubSubAdapter adapter will publish messages to MQTT topics in order to provide the ClearBlade Platform/Edge with data received from a Cloud Pub/Sub topic subscription. The topic structures utilized by the GooglePubSubAdapter adapter are as follows:

• Publish data to Cloud Pub/Sub: {TOPIC ROOT}/publish
• Send Cloud Pub/Sub subscription data to Clearblade: {TOPIC ROOT}/receive/response
• Adapter error conditions encountered: {TOPIC ROOT}/error

ClearBlade Platform Dependencies

The GooglePubSubAdapter adapter was constructed to provide the ability to communicate with a System defined in a ClearBlade Platform instance. Therefore, the adapter requires a System to have been created within a ClearBlade Platform instance.

Once a System has been created, artifacts must be defined within the ClearBlade Platform system to allow the adapters to function properly. At a minimum:

• A device needs to be created in the Auth --> Devices collection. The device will represent the adapter account. The name and active key values specified in the Auth --> Devices collection will be used by the adapter to authenticate to the ClearBlade Platform or ClearBlade Edge.
• An adapter configuration data collection needs to be created in the ClearBlade Platform system and populated with the data appropriate to the GooglePubSubAdapter adapter. The schema of the data collection should be as follows:

Column Name	Column Datatype
adapter_name	string
topic_root	string
adapter_settings	string (json)

adapter_settings

The adapter_settings column will need to contain a JSON object containing the following attributes:

gcpProjectID

• The ID of the GCP Project to connect to

gcpCredsPath

• The path to the json credential file used to authenticate with the Google Cloud Platform

gcpPubTopic

• The GCP Cloud PubSub topic the adapter should publish data to
• Optional, omit from settings object if you will not be publishing data to GCP Cloud Pub Sub

gcpSubTopic

• The GCP Cloud PubSub topic the adapter should subscribe to
• Optional, omit from settings object if you will not be subscribing to any GCP Cloud Pub Sub topic

gcpPullInterval

• The number of seconds to wait between each attempt to pull data from GCP Cloud Pub Sub

gcpSubPreCreated

• Boolean value that indicates whether or not the GCP Pub Sub subscription was pre-created in GCP
• If false, the adapter will attempt to create a subscription on GCP. This requires pubsub.editor permissions on GCP

adapter_settings_example

{ "gcpProjectID": "MyGcpProjectID", "gcpCredsPath": "/var/my_service_account_creds.json", "gcpPubTopic": "", "gcpSubTopic": "myTopic", "gcpPullInterval": 60, "gcpSubPreCreated": true }

Usage

Environment Variables

The Google PubSub Adapter is dependant upon certain environment variables prior to attempting to execute the adapter. The environment variables that need to be created are as follows:

CB_SYSTEM_KEY

• Optional, if no environment variable is created, use the systemKey command line flag

CB_SYSTEM_SECRET

• Optional, if no environment variable is created, use the systemSecret command line flag

CB_SERVICE_ACCOUNT

• REQUIRED
• The name of the device defined within the ClearBlade Platform or ClearBlade Edge representing the adapter

CB_SERVICE_ACCOUNT_TOKEN

• REQUIRED
• The authentication token of the device defined within the ClearBlade Platform or ClearBlade Edge representing the adapter

Environment variables can be created on Linux based systems by executing the following command from a terminal prompt: export [variable_name]=[variable_value]

example export CB_SERVICE_ACCOUNT=My_Device_Name export CB_SERVICE_ACCOUNT_TOKEN=MyDeviceToken

Executing the adapter

GooglePubSubAdapter -systemKey=<SYSTEM_KEY> -systemSecret=<SYSTEM_SECRET> -platformURL=<PLATFORM_URL> -messagingURL=<MESSAGING_URL> -adapterConfigCollection=<COLLECTION_NAME> -logLevel=<LOG_LEVEL>

Where

systemKey

• OPTIONAL
• Can be set up as an environment variable with the name CB_SYSTEM_KEY
• The system key of the ClearBLade Platform System the adapter will connect to

systemSecret

• OPTIONAL
• Can be set up as an environment variable with the name CB_SYSTEM_SECRET
• The system secret of the ClearBLade Platform System the adapter will connect to

platformURL

• The url of the ClearBlade Platform instance the adapter will connect to
• OPTIONAL
• Defaults to http://localhost:9000

messagingURL

• The MQTT url of the ClearBlade Platform instance the adapter will connect to
• OPTIONAL
• Defaults to localhost:1883

adapterConfigCollection

• The name of the data collection used to house adapter configuration data
• OPTIONAL
• Defaults to adapter_config

logLevel

• The level of runtime logging the adapter should provide.
• Available log levels:
  • FATAL
  • ERROR
  • INFO
  • DEBUG
• OPTIONAL
• Defaults to info

Setup

---

The GooglePubSubAdapter adapter is dependent upon the ClearBlade Go SDK and its dependent libraries being installed as well as the GCloud pubsub SDK. The GooglePubSubAdapter adapter was written in Go and therefore requires Go to be installed (https://golang.org/doc/install).

Adapter compilation

In order to compile the adapter for execution, the following steps need to be performed:

1. Retrieve the adapter source code
   • git clone git@github.com:ClearBlade/GooglePubSubAdapter.git
2. Navigate to the GooglePubSubAdapter directory
   • cd GooglePubSubAdapter
3. go get -u github.com/ClearBlade/Go-SDK.git
   • This command should be executed from within your Go workspace
4. go get -u cloud.google.com/go/pubsub
   • This command should be executed from within your Go workspace
5. Compile the adapter
   • go build