# Integrating with a Collector The Subscription API enables establishing a communication channel destination for events concerning environmental and operational status of selected assets. It supports AWS IoT Core, Azure Event Hub, and Webhook communication channels. > **Note** > > You can also create a subscription and access your data in the Equinix API. See [Stream Colocation Data from the Equinix API](https://docs.equinix.com/smart-view/sv-api/getoperatinginformation.md) for instructions. ## Equinix mTLS Certificate[​](#equinix-mtls-certificate "Direct link to Equinix mTLS Certificate") mTLS certificate is used as an extension of the TLS (former SSL) certificate for the server and client to authenticate each other. Equinix requires this trusted signed certificate from clients, similar to that provided by our services. Our subscription services offer you the additional option of connection verification. When a new batch of events is sent with each communication attempt, our subscription services use the certificates provided by the client to validate that the service we're sending the data to is the correct one. To retrieve the certificate, send a `GET` request to the [`/smartview/v2/streaming/subscriptions/certificate`](https://docs.equinix.com/api-catalog/smartviewv2/streaming-subscription-api/getcertificate.md) endpoint. Specify the channel destination as a query parameter, either `AWS_IOT_CORE` or `WEBHOOK`. Sample cURL Request: ``` curl -X 'GET' 'https://api.equinix.com/smartview/v2/streaming/subscriptions/certificate?channelType=WEBHOOK' \ -H 'Authorization: Bearer ' ``` > **Important** > > The Subscription API doesn't accept self-signed certificates. Use a CA certificate for mutual authentication. ## AWS IoT[​](#aws-iot "Direct link to AWS IoT") Send data to AWS IoT Core by providing the [HTTP endpoint](https://docs.aws.amazon.com/iot/latest/developerguide/http.html) when [creating your subscription](https://docs.equinix.com/smart-view/sv-api/create-subscription.md#aws-iot-core). > **Note** > > To authorize Equinix to send events to an AWS IoT Core destination, you must download the [Equinix Certificate](#equinix-mtls-certificate) and register it in IoT Core console. Refer to the [AWS Iot Core documentation](https://docs.aws.amazon.com/iot/latest/developerguide/manual-cert-registration.html) for instructions. ## Azure Event Hub[​](#azure-event-hub "Direct link to Azure Event Hub") Self-service configuration for sending data to Azure Event Hub is not available. To enable sending to data to Azure, [contact support](https://docs.equinix.com/customer-support/opening-support-case.md). ## Webhooks[​](#webhooks "Direct link to Webhooks") If you do not wish to use AWS or Azure as a collector, but you can provide a target URL to which streaming data can be sent, Equinix offers [creating a subscription to send data to a generic webhook destination](https://docs.equinix.com/smart-view/sv-api/create-subscription.md#webhook). ## Object Formats for Collectors[​](#object-formats-for-collectors "Direct link to Object Formats for Collectors") The message format for the AWS IoT Core and Azure Event Hubs channels makes the messages more readable. Here are some examples of messages that are sent over API Plus subscriptions. ### Environmental - temperature[​](#environmental---temperature "Direct link to Environmental - temperature") ``` { "type": "environmental", "data": { "ibx": "CH2", "asset": { "id": "asset1", "level": "ZONE" }, "reading": { "value": "23.300", "unit": "CELSIUS" }, "tag": { "id": "temperature", "displayName": "Temperature" }, "readingTime": "2020-08-24T09:21:00.000Z" } } ``` ### Environmental - humidity[​](#environmental---humidity "Direct link to Environmental - humidity") ``` { "type": "environmental", "data": { "ibx": "CH1", "asset": { "id": "asset1", "level": "ZONE" }, "reading": { "value": "66.120", "unit": "PERCENT" }, "tag": { "id": "humidity", "displayName": "Humidity" }, "readingTime": "2020-07-28T12:35:14.615Z" } } ``` ### Power[​](#power "Direct link to Power") ``` { "type": "power", "data": { "ibx": "SP2", "asset": { "id": "0210:469593", "type": "CIRCUIT" }, "cage": "ssxxxxsss", "cabinet": "SP2:01:021470:0210", "accountNumber": "1000659151", "realPower": { "value": "0.522", "unit": "kW" }, "apparentPower": { "value": "1.070", "unit": "kVA" }, "contractualPower": { "value": "60.000", "unit": "kVA" }, "current": { "value": "1.500", "unit": "A" }, "powerFactor": { "value": "0.48", "unit": "pf" }, "soldCurrent": { "value": "15.000", "unit": "A" }, "soldPower": { "value": "2.880", "unit": "kVA" }, "powerConsumptionToContractual": { "value": "32.151", "unit": "PERCENT" }, "cabinetRating": { "value": "123.300", "unit": "kVA" }, "peakLastSevenDays": { "value": "1.146", "unit": "kVA" }, "peakLastSevenDaysRatio": { "value": "34.424", "unit": "PERCENT" }, "peakLastSevenDaysContractualPower": { "value": "3.329", "unit": "kVA" }, "peakLastSevenDaysTime": "2020-07-29T07:00:00.000Z", "lastUpdated": "2020-07-24T11:46:00.000Z", "readingTime": "2020-07-24T11:45:00.000Z", "description": "test description", "oid": "1.3.6.1.2.1.299.2.10.6846", "circuitType": "primary", "customerName": "test customer" } } ``` ### Metered power - kWh[​](#metered-power---kwh "Direct link to Metered power - kWh") ``` { "type": "metered-power", "data": { "ibx": "LD9", "asset": { "id": "LD9.CBM-PDU-17-99", "type": "Customer Billing Meter" }, "cage": "LD9:0G:00Z13Z", "cageSerialNo": "00Z13B-21010567", "accountNumber": "1000006212", "customerName": "ABC Company", "kilowattHour": { "value": "304574.323", "unit": "kWh" }, "readingTime": "2023-04-24T11:45:00.000Z", "dataQuality": "Good" } } ``` Note: Metered power readings are available in kWh, kW, kVA, A, and pf (power factor) units. ### Tag-point[​](#tag-point "Direct link to Tag-point") ``` { "type": "tag-point", "data": { "ibx": "LA1", "reading": { "value": "33406.6", "unit": "l/s" }, "tag": { "id": "LA1.Air-Handler-7-4-4:totalsupplyairflow", "displayName": "Total Supply Air Flow" }, "readingTime": "2020-08-24T09:21:00.000Z" } } ``` ### Custom Alert[​](#custom-alert "Direct link to Custom Alert") ``` { "type": "alert", "data": { "ibx": "SG2", "region": "APAC", "asset": { "id": "CH1.Colo.CH1_05_000550_0105", "type": "ENVIRONMENTAL", "classification": "Environmental" }, "tag": { "id": "temperature" }, "threshold": { "unit": "CELSIUS", "maxValue": "-6.67", "minValue": "-12.22" }, "id": "zhe-15603221441540.3171591127612322145", "triggeredTime": "2019-09-23T23:01:30.655Z", "type": "environmental", "typeId": "Absolute", "conditional": "N", "eventType": "Out of Range", "heartbeat": false } } ``` ### System Alert[​](#system-alert "Direct link to System Alert") ``` { "type": "system-alert", "data": { "ibx": "SG2", "region": "APAC", "metro": "SG", "country": "SG", "currentValue": { "unit": "kWh", "value": "2.650479E7", "type": "float" }, "asset": { "id": "9SG2.ELEC4AUPSR-A10ASBF0", "type": "Circuit Breaker with Metering", "classification": "Electrical" }, "tag": { "id": "SG2.ELEC5BUPSR-B14UAH2Q:breaker", "displayName": "Bypass Not Available" }, "conditionName": "Low", "status": { "acknowledged": true, "acknowledgementTime": "2020-07-28T12:35:14.615Z", "cleared": false, "active": false }, "threshold": { "unit": "kWh", "stateLimit": "80", "message": "Drive not in Auto" }, "severity": 820, "triggeredTime": "2020-07-28T12:35:14.615Z", "processedTime": "2020-07-28T12:35:14.615Z", "normalProcessedTime": "2020-07-28T12:35:14.615Z", "normalTriggeredTime": "2020-07-28T12:35:14.615Z", "type": "Digital", "heartbeat": false } } ``` ### Data Quality Indicators[​](#data-quality-indicators "Direct link to Data Quality Indicators") The field `dataQuality` offers the Data Quality Indicators (DQI) of data points and alerts (system and custom) as part of the data itself. This is used to ensure and inform the API client that the data for DCIM assets is valid and collected reliably. The addition of DQI provides transparency regarding the quality of received data. ### Store and Forward Indicators[​](#store-and-forward-indicators "Direct link to Store and Forward Indicators") The field `messageRetried` as the Store and Forward Indicator (SNFI) is used to communicate if the DCIM data is actually near real-time or delayed and sent at a later time due to a disrupted connection through the NRT channel. If the connection between the subscription client and publisher has an issue, the publisher uses the Store and Forward (SNF) mechanism to store the message on the publisher's side. Once the connection is re-established, these stored messages and NRT events are sent to the client after the established connection time. The data sent later because of the SNFI method, is marked, as they are not NRT data anymore, compared to other normal data. Your API applications can make business rules and decisions based on both these indicators to improve data transparency and solution efficiency. ``` { "messageRetried": true, "type": "tag-point", "data": { "ibx": "SG2", "reading": { "value": "54.0", "unit": "s" }, "tag": { "id": "SG2.UPS-5-RM A22-04:batterytimeremaining", "displayName": "Battery Time Remaining" }, "readingTime": "2021-03-25T03:48:00.510Z", "dataQuality": "Good" } } ``` ## Interpreting ENUM and boolean values[​](#interpreting-enum-and-boolean-values "Direct link to Interpreting ENUM and boolean values") An Excel spreadsheet may be provided that includes columns similar to the following: | IBX | ASSET\_TYPE | ASSET\_CLASSIFICATION | ASSET\_ID | TAG\_SUFFIX | TAG\_ID | TAG\_DATA\_TYPE | TAG\_UOM | TAG\_DISPLAY\_NAME | STATE\_TABLE\_NAME | | --- | --------------------- | --------------------- | ------------------- | ------------ | -------------------------------- | --------------- | -------- | ------------------ | ----------------------------- | | TR5 | Fire, Smoke Detection | Mechanical | TR5.FireAlarm\_001 | alarm | TR5.FireAlarm\_001:alarm | Bool | | Alarm | NORMAL\_ALARM | | TR5 | Leak Detection | Mechanical | TR5.LD\_TR5\_CABLE1 | leakdetected | TR5.LD\_TR5\_CABLE1:leakdetected | Bool | | Leak Detected | NORMAL\_ALARM | | TR5 | UPS | Electrical | TR5.UPS\_2110 | resilient | TR5.UPS\_2110:resilient | Bool | | Resilient | REDUCEDRESIL\_RESILASDESIGNED | For boolean and ENUM values, refer to the `STATE_TABLE_NAME` when the first value (`NORMAL`, `REDUCEDRESIL`) corresponds to `0`, and the second value (`ALARM`, `RESILASDESIGNED`) corresponds to `1`. ## API call frequency[​](#api-call-frequency "Direct link to API call frequency") For the Power API, call it every 5 minutes for Asia-Pacific data centers, and every 15 minutes for other regions. The limit is 100,000 calls per user per day. For the Subscriptions API (REST collection method), call it approximately every 30 seconds per subscription ID. Calling up to once every 5 minutes is sufficient.