AZI: Python Scripting

The following API calls are available for the Azure Injector Module and can be executed within any of the available Ignition scopes.

createConfig
readConfig
updateConfig
deleteConfig

Configuration changes made through scripting do not have the same validation as when made through the UI.

For example, deleting a Sets configuring that is being referenced by a Servers configuration will result in the UI showing an Internal Error. Follow the instructions here to recover the configuration.

`APIs`

system.cirruslink.azure.createConfig(type, props) → void
- Parameters
  - type (str)
    - The type of configuration to create with valid options:
      - "Cert Files"
      - "IoT Hubs"
      - "IoT Edges"
      - "IoT Centrals"
      - "Event Hubs"
      - "Agents"
      - "Sets"
  - Map props
    - Dictionary of properties making up the configuration with the following keys and datatypes:
      - Cert Files
        Name (str)
        FileName (str)
        FileContents (str)
        Description (str)
      - IoT Hubs
        Id (long)(cannot be null)
        Name (str)
        Enabled (bool)
        Protocol (str) "MQTT"
        AzureSetId (long)(must be included)
        CertAuthEnabled (bool)
        ConnectionString (str)
        MqttHostname (str)
        DeviceId (str)
        CaCertFileId (long)
        ClientCertFileId (long)
        ClientPrivateKeyFileId (long)
        ClientKeyPassword (str)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(deprecated 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int)(added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        KeepAlive (int)
        MaxSize (int)
        Expiration (long)
        ContentType (str) "NONE" or "APPLICATION_JSON"
        ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
        CustomTopicExtension (str)
      - IoT Edges
        Id (long)(cannot be null)
        Name (str)
        Enabled (bool)
        Protocol (str) "MQTT"
        AzureSetId (long)(must be included)
        MqttServerUrl (str)
        CertAuthEnabled (bool)
        ConnectionString (str)
        CaCertFileId (long)
        ClientCertFileId (long)
        ClientPrivateKeyFileId (long)
        ClientKeyPassword (str)
        HostnameVerification (bool)
        MqttHostname (str)
        DeviceId (str)
        ModuleIdOption (str) "NONE", "ENVIRONMENT_VARIABLE" or "IGNITION_CONFIG"
        ModuleId (str)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(deprecated 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int)(added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        KeepAlive (int)
        MaxSize (int)
        Expiration (long)
        ContentType (str) "NONE" or "APPLICATION_JSON"
        ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
        CustomTopicExtension (str)
      - IoT Centrals
        Id (Long)(cannot be null)
        Name (str)
        Enabled (bool)
        ScopeId (str)
        EnrollmentGroupSymmetricKey (str)
        GlobalEndpoint (str)
        ProvisionedDeviceId (str)
        ModelId (str)
        AureSetId (long)(must be included)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(deprecated 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int)(added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        MaximumSize (int)
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPCOH" or "STRING_AZURE_COMPAT"
      - Event Hubs
        Id (long)(cannot be null)
        Name (str)
        Enabled (bool)
        AzureSetId(long)(must be included)
        CertAuthEnabled (bool)(added 4.0.26)
        TenantId (str)(added 4.0.26)
        AzureServicePrincipalClientId (str)(added 4.0.26)
        EventHubNamespace (str)(added 4.0.26)
        EventHubName (str)(added 4.0.26)
        ClientCertFileId (long)(added 4.0.26)
        ClientPrivateKeyFileId (long)(added 4.0.26)
        ClientKeyPassword (str)(added 4.0.26)
        ConnectionString (str)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(deprecated 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int)(added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        MaxSize (int)
        ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
      - Agents
        Id (long)(cannot be null)
        Name (str) (added 4.0.17)
        Enabled (bool) (added 4.0.17)
        TagProvider (str)
        TagPath (str)
        PushTrigger (str) "EVENT_DRIVEN", "PERIODIC" or "HYBRID"
        TagPacingPeriod (long)
        ConvertUdts (bool)
        PublishUdtDefinitions (bool)
        OptimizeUdts (bool)
        AzureSetId (long)(must be included)
        GroupId (str)
        EdgeNodeId (str)
        DeviceId (str)
        FilteredProperties (str)
        SendAllProps (bool)(added 4.0.25)
        IncludeInfoFolders (bool)(added 4.0.30)
      - Sets
        Id (long)(cannot be null)
        Name (str)
        Description (str)
        PushPolicy (str) "PUSH_TO_ALL" or "PUSH_TO_ANY"
- Return Value
  - A map representing the newly created configuration after it has been written to the database. (added 4.0.16)
system.cirruslink.azure.readConfig(type) → List
- Parameters
  - type (str)
    - The type of configuration to read with valid options:
      - "General"
      - "Cert Files"
      - "IoT Hubs"
      - "IoT Edges"
      - "IoT Centrals"
      - "Event Hubs"
      - "Agents"
      - "Sets"
- Return Value
  - A List of Dictionaries of properties making up the configurations with the following keys and datatypes:
    - General
      - Id (long)
      - Enabled (bool)
    - Cert Files
      - Name (str)
      - FileName (str)
      - FileContents (str)
      - Description (str)
    - IoT Hubs
      - Id (long)
      - Name (str)
      - Enabled (str)
      - Protocol (str) "MQTT"
      - AzureSetId (long)
      - CertAuthEnabled (bool)
      - ConnectionString (str)
      - MqttHostname (str)
      - DeviceId (str)
      - CaCertFileId (long)
      - ClientCertFileId (long)
      - ClientPrivateKeyFileId (long)
      - ClientKeyPassword (str)
      - HistoryEnabled (bool)
      - HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
      - MessageCapacity (int)(deprecated 4.0.19)
      - HistoryMaxSize (int)(added 4.0.22)
      - HistoryMaxAge (int)(added 4.0.19)
      - FlushPeriod (long)
      - H2dbDirectory (str)(added 4.0.25)
      - H2dbPort (int)(added 4.0.22)
      - KeepAlive (int)
      - MaxSize (int)
      - Expiration (long)
      - ContentType (str) "NONE" or "APPLICATION_JSON"
      - ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
      - AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
      - CustomTopicExtension (str)
    - IoT Edges
      - Id (long)
      - Name (str)
      - Enabled (str)
      - Protocol (str) "MQTT"
      - AzureSetId (long)
      - MqttServerUrl (str)
      - CertAuthEnabled (bool)
      - ConnectionString (str)
      - CaCertFileId (long)
      - ClientCertFileId (long)
      - ClientPrivateKeyFileId (long)
      - ClientKeyPassword (str)
      - HostnameVerification (bool)
      - MqttHostname (str)
      - DeviceId (str)
      - ModuleIdOption (str) "NONE", "ENVIRONMENT_VARIABLE" or "IGNITION_CONFIG"
      - ModuleId (str)
      - HistoryEnabled (bool)
      - HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
      - MessageCapacity (int)(deprecated 4.0.19)
      - HistoryMaxSize (int)(added 4.0.22)
      - HistoryMaxAge (int)(added 4.0.19)
      - FlushPeriod (long)
      - H2dbDirectory (str)(added 4.0.25)
      - H2dbPort (int)(added 4.0.22)
      - KeepAlive (int)
      - MaxSize (int)
      - Expiration (long)
      - ContentType (str) "NONE" or "APPLICATION_JSON"
      - ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
      - AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
      - CustomTopicExtension (str)
    - IoT Centrals
      - Id (long)
      - Name (str)
      - Enabled (bool)
      - ScopeId (str)
      - EnrollmentGroupSymmetricKey (str)
      - GlobalEndpoint (str)
      - ProvisionedDeviceId (str)
      - ModelId (str)
      - AzureSetId (str)
      - HistoryEnabled (bool)
      - HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
      - MessageCapacity (int)(deprecated 4.0.19)
      - HistoryMaxSize (int)(added 4.0.22)
      - HistoryMaxAge (int)(added 4.0.19)
      - FlushPeriod (long)
      - H2dbDirectory (str)(added 4.0.25)
      - H2dbPort (int)(added 4.0.22)
      - MaximumSize (int)
      - AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCK" or "STRING_AZURE_COMPAT"
    - Event Hubs
      - Id (long)
      - Name (str)
      - Enabled (str)
      - CertAuthEnabled (bool)(added 4.0.26)
      - TenantId (str)(added 4.0.26)
      - AzureServicePrincipalClientId (str)(added 4.0.26)
      - EventHubNamespace (str)(added 4.0.26)
      - EventHubName (str)(added 4.0.26)
      - ClientCertFileId (long)(added 4.0.26)
      - ClientPrivateKeyFileId (long)(added 4.0.26)
      - ClientKeyPassword (str)(added 4.0.26)
      - ConnectionString (str)
      - HistoryEnabled (bool)
      - HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
      - MessageCapacity (int)(deprecated 4.0.19)
      - HistoryMaxSize (int)(added 4.0.22)
      - HistoryMaxAge (int)(added 4.0.19)
      - FlushPeriod (long)
      - H2dbDirectory (str)(added 4.0.25)
      - H2dbPort (int)(added 4.0.22)
      - MaxSize (int)
      - ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
      - AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
    - Agents
      - Id (long)
      - Name (str) (added 4.0.17)
      - Enabled (bool) (added 4.0.17)
      - TagProvider (str)
      - TagPath (str)
      - PushTrigger (str) "EVENT_DRIVEN", "PERIODIC" or "HYBRID"
      - TagPacingPeriod (long)
      - ConvertUdts (bool)
      - PublishUdtDefinitions (bool)
      - OptimizeUdts (bool)
      - AzureSetId (long)
      - GroupId (str)
      - EdgeNodeId (str)
      - DeviceId (str)
      - FilteredProperties (str)
      - SendAllProps (bool)(added 4.0.25)
      - IncludeInfoFolders (bool)(added 4.0.30)
    - Sets
      - Id (long)
      - Name (str)
      - Description (str)
      - PushPolicy (str) "PUSH_TO_ALL" or "PUSH_TO_ANY"
system.cirruslink.azure.updateConfig(type, id, collisionPolicy, props) → void
- Parameters
  - Type (str)
    - The type of configuration to update with valid options:
      - "General"
      - "Cert Files"
      - "IoT Hubs"
      - "IoT Edges"
      - "IoT Centrals"
      - "Event Hubs"
      - "Agents"
      - "Sets"
  - Id (long)
    - The ID of the record to update
  - collisionPolicy(str)
    - "MergeOverwrite" or "Overwrite"
      - "MergeOverwrite" will replace the existing properties in the record ID with only those included in the call
      - "Overwrite" will replace all properties in the record ID with those in the call
  - Map props
    - Dictionary of properties making up the configuration with the following keys and datatypes:
      - General
        Id (long)
        Enabled (bool)
      - Cert Files
        Name (str)
        FileName (str)
        FileContents (str)
        Description (str)
      - IoT Hubs
        Id (long)
        Name (str)
        Enabled (str)
        Protocol (str) "MQTT"
        AzureSetId (long)
        CertAuthEnabled (bool)
        ConnectionString (str)
        MqttHostname (str)
        DeviceId (str)
        CaCertFileId (long)
        ClientCertFileId (long)
        ClientPrivateKeyFileId (long)
        ClientKeyPassword (str)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(deprecated 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int) (added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        KeepAlive (int)
        MaxSize (int)
        Expiration (long)
        ContentType (str) "NONE" or "APPLICATION_JSON"
        ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
        CustomTopicExtension (str)
      - IoT Edges
        Id (long)
        Name (str)
        Enabled (str)
        Protocol (str) "MQTT"
        AzureSetId (long)
        MqttServerUrl (str)
        CertAuthEnabled (bool)
        ConnectionString (str)
        CaCertFileId (long)
        ClientCertFileId (long)
        ClientPrivateKeyFileId (long)
        ClientKeyPassword (str)
        HostnameVerification (bool)
        MqttHostname (str)
        DeviceId (str)
        ModuleIdOption (str) "NONE", "ENVIRONMENT_VARIABLE" or "IGNITION_CONFIG"
        ModuleId (str)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(deprecated 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int)(added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        KeepAlive (int)
        MaxSize (int)
        Expiration (long)
        ContentType (str) "NONE" or "APPLICATION_JSON"
        ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
        CustomTopicExtension (str)
      - IoT Centrals
        Id (long)
        Name (str)
        Enabled (bool)
        ScopeId (str)
        EnrollmentGroupSymmetricKey (str)
        GlobalEndpoint (str)
        ModelId (str)
        AzureSetId (long)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(depreacted 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int)(added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        MaximumSize (int)
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
      - Event Hubs
        Id (long)
        Name (str)
        Enabled (str)
        CertAuthEnabled (bool)(added 4.0.26)
        TenantId (str)(added 4.0.26)
        AzureServicePrincipalClientId (str)(added 4.0.26)
        EventHubNamespace (str)(added 4.0.26)
        EventHubName (str)(added 4.0.26)
        ClientCertFileId (long)(added 4.0.26)
        ClientPrivateKeyFileId (long)(added 4.0.26)
        ClientKeyPassword (str)(added 4.0.26)
        ConnectionString (str)
        HistoryEnabled (bool)
        HistoryStoreType (str) "In_Memory" or "Disk_Backed" (added 4.0.17)
        MessageCapacity (int)(deprecated 4.0.19)
        HistoryMaxSize (int)(added 4.0.22)
        HistoryMaxAge (int)(added 4.0.19)
        FlushPeriod (long)
        H2dbDirectory (str)(added 4.0.25)
        H2dbPort (int)(added 4.0.22)
        MaxSize (int)
        ContentEncoding (str) "NONE", "UTF_8", "UTF_16", or "UTF_32"
        AzureDateTimeFormat (str) "LONG_MS_SINCE_EPOCH" or "STRING_AZURE_COMPAT"
      - Agents
        Id (long)
        Name (str) (added 4.0.17)
        Enabled (bool) (added 4.0.17)
        TagProvider (str)
        TagPath (str)
        PushTrigger (str) "EVENT_DRIVEN", "PERIODIC" or "HYBRID"
        TagPacingPeriod (long)
        ConvertUdts (bool)
        PublishUdtDefinitions (bool)
        OptimizeUdts (bool)
        AzureSetId (long)
        GroupId (str)
        EdgeNodeId (str)
        DeviceId (str)
        FilteredProperties (str)
        SendAllProps (bool)(added 4.0.25)
        IncludeInfoFolders (bool)(added 4.0.30)
      - Sets
        Id (long)
        Name (str)
        Description (str)
        PushPolicy (str) "PUSH_TO_ALL" or "PUSH_TO_ANY"
- Return Value
  - A map representing the updated configuration after it has been written to the database. (added 4.0.16)
system.cirruslink.azure.deleteConfig(type, id) → void
- Parameters
  - Type (str)
    - The type of configuration to delete with valid options:
      - "Cert Files"
      - "IoT Hubs"
      - "IoT Edges"
      - "IoT Centrals"
      - "Event Hubs"
      - "Agents"
      - "Sets"
  - Id (long)
    - The ID of the record to delete
- Return Value
  - True if the record was successfully deleted otherwise False (added 4.0.16)

Sample Script

Cirrus Link provides these scripts as examples only, they are not supported or guaranteed to meet any particular functionality. Cirrus Link cannot provide any assistance to modify these scripts to meet a particular need.

# Cirrus Link provides these scripts as examples only, they are not supported or guaranteed to meet any particular functionality. Cirrus Link cannot provide any assistance to modify these scripts to meet a particular need
# Update Certificates
# Get Id for current certificate
savedCerts = system.cirruslink.azure.readConfig("Cert Files")
for config in savedCerts:
  if config["Name"] == "My current cert name":
    certId = config["Id"]

# Read New Cert File
deviceCaCertFilePath = "/path/to/your/certs/iot-edge-device-ca-CA.cert.pem"
deviceCaCert = open(deviceCaCertFilePath, 'r').read()

# Update existing cert config using MergeOverwrite
certProps = {}
certProps["FileContents"] = deviceCaCert
system.cirruslink.azure.updateConfig(“Cert Files”, certId, “MergeOverwrite”, certProps)

Contents

Cirrus Link Resources

Inductive Resources

`APIs`

Sample Script