| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <meta name="description" content=""> |
| <meta name="keywords" content="connectivity, connection, connectivity, mapping, connection, integration, placeholder, qos, at least once, delivery, guarantee"> |
| <title> Connections • Eclipse Ditto • a digital twin framework</title> |
| |
| <link rel="stylesheet" href="css/syntax.css"> |
| <link rel="stylesheet" type="text/css" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" crossorigin="anonymous"> |
| <link rel="stylesheet" href="css/modern-business.css"> |
| <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" crossorigin="anonymous"> |
| <link rel="stylesheet" href="css/customstyles.css"> |
| <link rel="stylesheet" href="css/boxshadowproperties.css"> |
| <link rel="stylesheet" href="css/theme-ditto.css"> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700"> |
| |
| <script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js" crossorigin="anonymous"></script> |
| <script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js" crossorigin="anonymous"></script> |
| <script src="//cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js" crossorigin="anonymous"></script> |
| <script src="js/toc.js"></script> |
| <script src="js/customscripts.js"></script> |
| |
| <script type="application/ld+json"> |
| { |
| "@context": "http://schema.org", |
| "@type": "Organization", |
| "url": "https://eclipse.org/ditto/", |
| "logo": "https://eclipse.org/ditto/images/ditto.svg" |
| } |
| </script> |
| |
| <link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16"> |
| <link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32"> |
| <link rel="icon" type="image/png" href="images/favicon-96x96.png" sizes="96x96"> |
| |
| <link rel="alternate" type="application/rss+xml" title="Eclipse Ditto Blog" href="https://www.eclipse.org/ditto/feed.xml"> |
| |
| <!-- Eclipse Foundation cookie consent: --> |
| <link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" /> |
| <script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script> |
| |
| <script> |
| $(document).ready(function() { |
| $("#tg-sb-link").click(function() { |
| $("#tg-sb-sidebar").toggle(); |
| $("#tg-sb-content").toggleClass('col-md-9'); |
| $("#tg-sb-content").toggleClass('col-md-12'); |
| $("#tg-sb-icon").toggleClass('fa-toggle-on'); |
| $("#tg-sb-icon").toggleClass('fa-toggle-off'); |
| }); |
| }); |
| </script> |
| </head> |
| |
| |
| <script> |
| (function(w,d,s,l,i){ |
| w[l]=w[l]||[]; |
| w[l].push({'gtm.start': |
| new Date().getTime(),event:'gtm.js'}); |
| var f=d.getElementsByTagName(s)[0], |
| j=d.createElement(s), |
| dl=l!='dataLayer'?'&l='+l:''; |
| j.async=true; |
| j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl; |
| f.parentNode.insertBefore(j,f); |
| })(window,document,'script','dataLayer','GTM-5WLCZXC'); |
| </script> |
| |
| |
| |
| <body> |
| <!-- Navigation --> |
| <nav class="navbar navbar-inverse navbar-fixed-top"> |
| <div class="container topnavlinks"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-ditto-home" href="index.html"> <img src="images/ditto_allwhite_symbolonly.svg" class="ditto-navbar-symbol" alt="Home"> <img src="images/ditto_allwhite_textonly.svg" class="ditto-navbar-symbol-text" alt="Ditto"></a> |
| </div> |
| <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> |
| <ul class="nav navbar-nav navbar-right"> |
| <!-- toggle sidebar button --> |
| <!--<li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>--> |
| <!-- entries without drop-downs appear here --> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="blog.html">Blog</a></li> |
| |
| |
| |
| <li><a href="intro-overview.html">Documentation</a></li> |
| |
| |
| |
| <li><a href="http-api-doc.html">HTTP API</a></li> |
| |
| |
| |
| <li><a href="sandbox.html">Sandbox</a></li> |
| |
| |
| |
| <li><a href="https://github.com/eclipse/ditto" target="_blank">GitHub</a></li> |
| |
| |
| |
| <li><a href="https://github.com/eclipse/ditto-examples" target="_blank">GitHub examples</a></li> |
| |
| |
| |
| <!-- entries with drop-downs appear here --> |
| <!-- conditional logic to control which topnav appears for the audience defined in the configuration file.--> |
| |
| |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Links<b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| |
| |
| <li><a href="https://projects.eclipse.org/projects/iot.ditto" target="_blank">Eclipse Ditto Project</a></li> |
| |
| |
| |
| <li><a href="https://www.eclipse.org/forums/index.php/f/364/" target="_blank">Forum</a></li> |
| |
| |
| |
| <li><a href="https://ci.eclipse.org/ditto/" target="_blank">Jenkins</a></li> |
| |
| |
| |
| <li><a href="https://dev.eclipse.org/mhonarc/lists/ditto-dev/" target="_blank">Mailing list archives</a></li> |
| |
| |
| |
| <li><a href="https://gitter.im/eclipse/ditto" target="_blank">Gitter.im chat</a></li> |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| <!--comment out this block if you want to hide search--> |
| <li> |
| <!--start search--> |
| <div id="search-demo-container"> |
| <input type="text" id="search-input" placeholder="search..."> |
| <ul id="results-container"></ul> |
| </div> |
| <script src="//cdnjs.cloudflare.com/ajax/libs/simple-jekyll-search/0.0.9/jekyll-search.js" type="text/javascript"></script> |
| <script type="text/javascript"> |
| SimpleJekyllSearch.init({ |
| searchInput: document.getElementById('search-input'), |
| resultsContainer: document.getElementById('results-container'), |
| dataSource: 'search.json', |
| searchResultTemplate: '<li><a href="{url}" title="Connections">{title}</a></li>', |
| noResultsText: 'No results found.', |
| limit: 10, |
| fuzzy: true, |
| }) |
| </script> |
| <!--end search--> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <!-- /.container --> |
| </nav> |
| |
| <!-- Page Content --> |
| <div class="container"> |
| <div id="main"> |
| <!-- Content Row --> |
| <div class="row"> |
| |
| |
| <!-- Sidebar Column --> |
| <div class="col-md-3" id="tg-sb-sidebar"> |
| |
| |
| <ul id="mysidebar" class="nav"> |
| <li class="sidebarTitle"> |
| <label for="docVersion">Eclipse Ditto version:</label> |
| <div class="select-wrapper"> |
| <select id="docVersion" name="docVersion"> |
| |
| <option value="">development</option> |
| |
| <option value="1.0">1.0</option> |
| |
| <option value="1.1">1.1</option> |
| |
| <option value="1.2">1.2</option> |
| |
| <option value="1.3">1.3</option> |
| |
| <option value="1.4">1.4</option> |
| |
| <option value="1.5">1.5</option> |
| |
| </select> |
| </div> |
| <div id="dev-warning"> |
| <div markdown="span" class="alert alert-warning" role="alert" style="font-size:0.6em"><i class="fa fa-warning"></i> <b>Important:</b> This documentation reflects the latest 'development'. You might want to choose a released version.</div> |
| </div> |
| </li> |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Introduction</a> |
| <ul> |
| |
| |
| |
| <li><a href="intro-overview.html">Overview</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="intro-digitaltwins.html">Digital twins</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="intro-hello-world.html">Hello world</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Release Notes</a> |
| <ul> |
| |
| |
| |
| <li><a href="release_notes_130.html">1.3.0</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_121.html">1.2.1</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_120.html">1.2.0</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_115.html">1.1.5</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_113.html">1.1.3</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_112.html">1.1.2</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_111.html">1.1.1</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_110.html">1.1.0</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_100.html">1.0.0</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_090.html">0.9.0</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_080.html">0.8.0</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Milestone releases</a> |
| <ul> |
| |
| |
| |
| <li><a href="release_notes_100-M2.html">1.0.0-M2</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_100-M1a.html">1.0.0-M1a</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_090-M2.html">0.9.0-M2</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_090-M1.html">0.9.0-M1</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_080-M3.html">0.8.0-M3</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_080-M2.html">0.8.0-M2</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_080-M1.html">0.8.0-M1</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_030-M2.html">0.3.0-M2</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_030-M1.html">0.3.0-M1</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_020-M1.html">0.2.0-M1</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_010-M3.html">0.1.0-M3</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_010-M1.html">0.1.0-M1</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Installation</a> |
| <ul> |
| |
| |
| |
| <li><a href="installation-building.html">Building Ditto</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="installation-running.html">Running Ditto</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="installation-operating.html">Operating Ditto</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Basic concepts</a> |
| <ul> |
| |
| |
| |
| <li><a href="basic-overview.html">Overview</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Model entities</a> |
| <ul> |
| |
| |
| |
| <li><a href="basic-thing.html">Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-acl.html">Access Control List (ACL)</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-feature.html">Feature</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-policy.html">Policy</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-namespaces-and-names.html">Namespaces and Names</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-metadata.html">Thing Metadata</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-errors.html">Errors</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-auth.html">Authentication and Authorization</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-messages.html">Messages</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-signals.html">Signals</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Signal types</a> |
| <ul> |
| |
| |
| |
| <li><a href="basic-signals-command.html">Command</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-signals-commandresponse.html">Command response</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-signals-errorresponse.html">Error response</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-signals-event.html">Event</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-apis.html">APIs</a></li> |
| |
| |
| |
| |
| |
| |
| <li class="active"><a href="basic-connections.html">Connections</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-placeholders.html">Placeholders</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-changenotifications.html">Change notifications</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-rql.html">RQL expressions</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-enrichment.html">Signal enrichment</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-search.html">Search</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="basic-acknowledgements.html">Acknowledgements / QoS</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Architecture</a> |
| <ul> |
| |
| |
| |
| <li><a href="architecture-overview.html">Overview</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Services</a> |
| <ul> |
| |
| |
| |
| <li><a href="architecture-services-policies.html">Policies</a></li> |
| |
| |
| |
| |
| |
| <li><a href="architecture-services-things.html">Things</a></li> |
| |
| |
| |
| |
| |
| <li><a href="architecture-services-things-search.html">Things-Search</a></li> |
| |
| |
| |
| |
| |
| <li><a href="architecture-services-connectivity.html">Connectivity</a></li> |
| |
| |
| |
| |
| |
| <li><a href="architecture-services-concierge.html">Concierge</a></li> |
| |
| |
| |
| |
| |
| <li><a href="architecture-services-gateway.html">Gateway</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>HTTP API</a> |
| <ul> |
| |
| |
| |
| <li><a href="httpapi-overview.html">Overview</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="httpapi-concepts.html">Concepts</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="httpapi-search.html">Search</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="httpapi-messages.html">Messages</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="httpapi-protocol-bindings-websocket.html">WebSocket protocol binding</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="httpapi-sse.html">Server sent events</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Connectivity API</a> |
| <ul> |
| |
| |
| |
| <li><a href="connectivity-overview.html">Overview</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-manage-connections.html">Manage connections</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1 protocol binding</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0 protocol binding</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1 protocol binding</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5 protocol binding</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1 protocol binding</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x protocol binding</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-mapping.html">Payload mapping</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-header-mapping.html">Header mapping</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-tls-certificates.html">TLS certificates</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Client SDK</a> |
| <ul> |
| |
| |
| |
| <li><a href="client-sdk-overview.html">Overview</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="client-sdk-java.html">Java</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="client-sdk-javascript.html">JavaScript</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Ditto Protocol</a> |
| <ul> |
| |
| |
| |
| <li><a href="protocol-overview.html">Overview</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-twinlive.html">Twin/live channel</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification.html">Specification</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-topic.html">Protocol topic</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-things.html">Things group</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>→ commands/events</a> |
| <ul> |
| |
| |
| |
| <li><a href="protocol-specification-things-create-or-modify.html">Create/Modify</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-things-retrieve.html">Retrieve</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-things-delete.html">Delete</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-acks.html">Acknowledgements</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-errors.html">Errors</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>→ search/messages</a> |
| <ul> |
| |
| |
| |
| <li><a href="protocol-specification-things-search.html">Search</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-things-messages.html">Messages</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-policies.html">Policies group</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>→ commands/events</a> |
| <ul> |
| |
| |
| |
| <li><a href="protocol-specification-policies-create-or-modify.html">Create/Modify</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-policies-retrieve.html">Retrieve</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-policies-delete.html">Delete</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-bindings.html">Bindings</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples.html">Examples</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>→ Things examples</a> |
| <ul> |
| |
| |
| |
| <li><a href="protocol-examples-creatething.html">Create a Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deletething.html">Delete a Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifything.html">Modify a Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievething.html">Retrieve a Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievethings.html">Retrieve multiple Things</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifypolicyid.html">Modify the Policy ID of a Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createattributes.html">Create Attributes</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deleteattributes.html">Delete Attributes</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifyattributes.html">Modify Attributes</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrieveattributes.html">Retrieve Attributes</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createattribute.html">Create a single Attribute</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deleteattribute.html">Delete a single Attribute</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifyattribute.html">Modify a single Attribute</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrieveattribute.html">Retrieve a single Attribute</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createthingdefinition.html">Create a Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deletethingdefinition.html">Delete a Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifythingdefinition.html">Modify a Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievethingdefinition.html">Retrieve a Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createfeatures.html">Create Features</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deletefeatures.html">Delete Features</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifyfeatures.html">Modify Features</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievefeatures.html">Retrieve Features</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createfeature.html">Create a single Feature</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deletefeature.html">Delete a single Feature</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifyfeature.html">Modify a single Feature</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievefeature.html">Retrieve a single Feature</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createdefinition.html">Create Feature Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deletedefinition.html">Delete Feature Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifydefinition.html">Modify Feature Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievedefinition.html">Retrieve Feature Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createproperties.html">Create Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deleteproperties.html">Delete Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifyproperties.html">Modify Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrieveproperties.html">Retrieve Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createproperty.html">Create a single Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deleteproperty.html">Delete a single Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifyproperty.html">Modify a single Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrieveproperty.html">Retrieve a single Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-errorresponses.html">Error responses</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>→ Policies examples</a> |
| <ul> |
| |
| |
| |
| <li><a href="protocol-examples-policies-createpolicy.html">Create a Policy</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-deletepolicy.html">Delete a Policy</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-modifypolicy.html">Modify a Policy</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-retrievepolicy.html">Retrieve a Policy</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-modifypolicyentries.html">Modify entries</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-retrievepolicyentries.html">Retrieve entries</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-createpolicyentry.html">Create a single entry</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-deletepolicyentry.html">Delete a single entry</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-modifypolicyentry.html">Modify a single entry</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-retrievepolicyentry.html">Retrieve a single entry</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-modifysubjects.html">Modify subjects</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-retrievesubjects.html">Retrieve subjects</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-createsubject.html">Create a single subject</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-deletesubject.html">Delete a single subject</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-modifysubject.html">Modify a single subject</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-retrievesubject.html">Retrieve a single subject</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-modifyresources.html">Modify resources</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-retrieveresources.html">Retrieve resources</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-createresource.html">Create a single resource</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-deleteresource.html">Delete a single resource</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-modifyresource.html">Modify a single resource</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-retrieveresource.html">Retrieve a single resource</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-errorresponses.html">Error responses</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-search.html">→ Search examples</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li><a href="sandbox.html">Sandbox</a></li> |
| |
| |
| |
| |
| |
| <li><a href="presentations.html">Presentations</a></li> |
| |
| |
| |
| |
| |
| <li><a href="glossary.html">Glossary</a></li> |
| |
| |
| |
| |
| |
| <li><a href="feedback.html">Feedback</a></li> |
| |
| |
| |
| |
| |
| <p class="external"> |
| <a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a> |
| </p> |
| |
| </ul> |
| |
| <!-- this highlights the active parent class in the sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.--> |
| <script>$("li.active").parents('li').toggleClass("active"); |
| </script> |
| |
| </div> |
| |
| |
| |
| <!-- Content Column --> |
| <div class="col-md-9" id="tg-sb-content"> |
| <div class="post-header"> |
| <h1 class="post-title-main">Connections</h1> |
| </div> |
| |
| |
| |
| <div class="post-content"> |
| |
| |
| |
| |
| |
| <!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. --> |
| <script> |
| $( document ).ready(function() { |
| // Handler for .ready() called. |
| |
| $('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' }); |
| |
| /* this offset helps account for the space taken up by the floating toolbar. */ |
| $('#toc').on('click', 'a', function() { |
| var target = $(this.getAttribute('href')) |
| , scroll_target = target.offset().top |
| |
| $(window).scrollTop(scroll_target - 10); |
| return false |
| }) |
| |
| }); |
| </script> |
| |
| <div id="toc"></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h2 id="connection-model">Connection model</h2> |
| |
| <div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> To get started with connections right away, consult the |
| <a href="connectivity-manage-connections.html">Manage connections</a> |
| page. </div> |
| |
| <p>You can integrate your Ditto instance with external messaging services such as |
| <a href="https://eclipse.org/hono/">Eclipse Hono</a>, a <a href="https://www.rabbitmq.com/">RabbitMQ</a> broker or an |
| <a href="https://kafka.apache.org/">Apache Kafka</a> broker via custom “connections”.</p> |
| |
| <p>Additionally, you may invoke foreign HTTP endpoints by using the |
| <a href="connectivity-protocol-bindings-http.html">HTTP connection type</a>.</p> |
| |
| <p>A connection represents a communication channel for the exchange of messages between any service and Ditto. It |
| requires a transport protocol, which is used to transmit <a href="protocol-overview.html">Ditto Protocol</a> messages. Ditto supports one-way and two-way |
| communication over connections. This enables consumer/producer scenarios as well as fully-fledged command and response |
| use cases. Nevertheless, those options might be limited by the transport protocol or the other endpoint’s |
| capabilities.</p> |
| |
| <p>All connections are configured and supervised via Ditto’s |
| <a href="architecture-services-connectivity.html">Connectivity service</a>. The following model defines the connection itself:</p> |
| |
| <script src="docson/widget.js" data-schema="../jsonschema/connection.json"></script> |
| |
| <h3 id="connection-types">Connection types</h3> |
| |
| <p>The top design priority of this model is to be as generic as possible, while still allowing protocol specific |
| customizations and tweaks. This enables the implementations of different customizable connection types, and support |
| for custom payload formats. Currently the following connection types are supported:</p> |
| |
| <ul> |
| <li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1</a></li> |
| <li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0</a></li> |
| <li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1</a></li> |
| <li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5</a></li> |
| <li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1</a></li> |
| <li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x</a></li> |
| </ul> |
| |
| <p>The <code class="highlighter-rouge">sources</code> and <code class="highlighter-rouge">targets</code> address formats depends on the <code class="highlighter-rouge">connectionType</code> and has therefore <code class="highlighter-rouge">connectionType</code> |
| specific limitations. Those are documented with the corresponding protocol bindings.</p> |
| |
| <h3 id="sources">Sources</h3> |
| |
| <p>Sources are used to connect to message brokers / external systems in order to consume messages <strong>from them</strong>.</p> |
| |
| <p>Source messages can be of the following type:</p> |
| <ul> |
| <li><a href="basic-signals-command.html">commands</a></li> |
| <li><a href="basic-messages.html">messages</a></li> |
| <li><a href="protocol-twinlive.html">live commands/responses/events</a></li> |
| </ul> |
| |
| <p>Sources contain:</p> |
| <ul> |
| <li>several addresses (depending on the <a href="#connection-types">connection type</a> those are interpreted differently, e.g. as queues, topics, etc.),</li> |
| <li>a consumer count defining how many consumers should be attached to each source address,</li> |
| <li>an authorization context (see <a href="#authorization">authorization</a>) specifying which <a href="basic-acl.html#authorization-subject">authorization subject</a> is used to authorize messages from the source,</li> |
| <li>enforcement information that allows filtering the messages that are consumed in this source,</li> |
| <li><a href="basic-acknowledgements.html#requesting-acks">acknowledgement requests</a> this source requires in order to ensure QoS 1 (“at least once”) processing of consumed messages before technically acknowledging them to the channel,</li> |
| <li><a href="connectivity-header-mapping.html">header mapping</a> for mapping headers of source messages to internal headers, and</li> |
| <li>a reply-target to configure publication of any responses of incoming commands.</li> |
| </ul> |
| |
| <h4 id="source-enforcement">Source enforcement</h4> |
| |
| <p>Messages received from external systems are mapped to Ditto internal format, either by applying some custom mapping or |
| the default mapping for <a href="protocol-overview.html">Ditto Protocol</a> messages.</p> |
| |
| <p>During this mapping the digital twin of the device is determined i.e. |
| which thing is accessed or modified as a result of the message. By default, no sanity check is done if this target thing |
| corresponds to the device that originally sent the message. In some use cases this might be valid, but in other scenarios |
| you might want to enforce that a device only sends data to its digital twin. Note that this could also be achieved by |
| assigning a specific policy to each device and use <a href="#placeholders">placeholders</a> in the |
| authorization subject, but this can get cumbersome to maintain for a large number of devices.</p> |
| |
| <p>With an enforcement, you can use a single policy for all devices |
| and still make sure that a device only modifies its associated digital twin. Enforcement is only feasible if the message |
| contains the verified identity of the sending device (e.g. in a message header). This verification has to be done by the |
| external system e.g. by properly authenticating the devices and providing the identity in the messages sent to Ditto.</p> |
| |
| <p>The enforcement configuration consists of two fields:</p> |
| <ul> |
| <li><code class="highlighter-rouge">input</code>: Defines where device identity is extracted.</li> |
| <li><code class="highlighter-rouge">filters</code>: Defines the filters that are matched against the input. At least one filter must match the input value, |
| otherwise the message is rejected.</li> |
| </ul> |
| |
| <p>The following placeholders are available for the <code class="highlighter-rouge">input</code> field:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Placeholder</th> |
| <th>Description</th> |
| <th>Example</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code class="highlighter-rouge">{{ header:<name> }}</code></td> |
| <td>Any header from the message received via the source.</td> |
| <td><code class="highlighter-rouge">{{header:device_id }}</code></td> |
| </tr> |
| <tr> |
| <td><code class="highlighter-rouge">{{ source:address }}</code></td> |
| <td>The address on which the message was received.</td> |
| <td>devices/sensors/temperature1</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>The following placeholders are available for the <code class="highlighter-rouge">filters</code> field:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Placeholder</th> |
| <th>Description</th> |
| <th>Example</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code class="highlighter-rouge">{{ thing:id }}</code></td> |
| <td>Full ID composed of ‘‘namespace’’ + ‘’:’’ as a separator + ‘‘name’’</td> |
| <td>eclipse.ditto:thing-42</td> |
| </tr> |
| <tr> |
| <td><code class="highlighter-rouge">{{ thing:namespace }}</code></td> |
| <td>Namespace (i.e. first part of an ID)</td> |
| <td>eclipse.ditto</td> |
| </tr> |
| <tr> |
| <td><code class="highlighter-rouge">{{ thing:name }}</code></td> |
| <td>Name (i.e. second part of an ID )</td> |
| <td>thing-42</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>Assuming a device <code class="highlighter-rouge">sensor:temperature1</code> pushes its telemetry data to Ditto which is stored in a thing named |
| <code class="highlighter-rouge">sensor:temperature1</code>. The device identity is provided in a header field <code class="highlighter-rouge">device_id</code>. To enforce that the device can |
| only send data to the Thing <code class="highlighter-rouge">sensor:temperature1</code> the following enforcement configuration can be used:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"telemetry/hono_tenant"</span><span class="w"> </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"enforcement"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"input"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:device_id }}"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"filters"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"{{ thing:id }}"</span><span class="w"> </span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>Note: This example assumes that there is a valid user named <code class="highlighter-rouge">ditto:inbound-auth-subject</code> in Ditto. |
| If you want to use a user for the basic auth (from the <a href="connectivity-protocol-bindings-http.html">HTTP API</a>) use the prefix <code class="highlighter-rouge">nginx:</code>, e.g. <code class="highlighter-rouge">nginx:ditto</code>. |
| See <a href="basic-auth.html#authorization-context-in-devops-commands">Basic Authentication</a> for more information.</p> |
| |
| <h4 id="source-acknowledgement-requests">Source acknowledgement requests</h4> |
| |
| <p>A source can configure, that for each incoming message additional |
| <a href="basic-acknowledgements.html#requesting-acks">acknowledgement requests</a> are added.</p> |
| |
| <p>That is desirable whenever incoming messages should be processed with a higher “quality of service” than the default, |
| which is “at most once” (or QoS 0).</p> |
| |
| <p>In order to process messages from sources with an “at least once” (or QoS 1) semantic, configure the source’s |
| <code class="highlighter-rouge">"acknowledgementRequests/includes"</code> to add the |
| <a href="basic-acknowledgements.html#built-in-acknowledgement-labels">“twin-persisted”</a> acknowledgement request, which will cause |
| that a consumed message over this source will technically be acknowledged, it the twin was |
| successfully updated/persisted by Ditto.</p> |
| |
| <p>How the technical acknowledgment is done is specific for the used <a href="#connection-types">connection type</a> and documented |
| in scope of that connection type.</p> |
| |
| <p>In addition to the <code class="highlighter-rouge">"includes"</code> defining which acknowledgements to request for each incoming message, the optional |
| <code class="highlighter-rouge">"filter"</code> holds an <a href="basic-placeholders.html#function-library">fn:filter()</a> function defining when to request |
| acknowledgements at all for an incoming message. This filter is applied on both acknowledgements: those |
| <a href="basic-acknowledgements.html#requesting-acks-via-ditto-protocol-message">requested in the message</a> and the ones requested |
| via the configured <code class="highlighter-rouge">"includes"</code> array.</p> |
| |
| <p>The JSON for a source with acknowledgement requests could look like this. The <code class="highlighter-rouge">"filter"</code> in the example causes that |
| acknowledgements are only requested if the “qos” header was either not present or does not equal <code class="highlighter-rouge">0</code>:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"<source>"</span><span class="w"> |
| </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"qos"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:qos }}"</span><span class="w"> |
| </span><span class="p">},</span><span class="w"> |
| </span><span class="s2">"acknowledgementRequests"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"includes"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"twin-persisted"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"my-custom-ack"</span><span class="w"> |
| </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"filter"</span><span class="p">:</span><span class="w"> </span><span class="s2">"fn:filter(header:qos,'ne',0)"</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h4 id="source-header-mapping">Source header mapping</h4> |
| |
| <p>For incoming messages, an optional <a href="connectivity-header-mapping.html">header mapping</a> may be applied. |
| Mapped headers are added to the headers of the Ditto protocol message obtained by payload mapping. |
| The default <a href="connectivity-mapping.html#ditto-mapper">Ditto payload mapper</a> does not retain any external header; |
| in this case all Ditto protocol headers come from the header mapping.</p> |
| |
| <p>The JSON for a source with header mapping could look like this:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"<source>"</span><span class="w"> |
| </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"correlation-id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:message-id }}"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"content-type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:content-type }}"</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h4 id="source-reply-target">Source reply target</h4> |
| |
| <p>A source may define a reply target to publish the responses of incoming commands. |
| For a reply target, the address and header mapping are defined in itself, whereas its payload mapping is inherited |
| from the parent source, because a payload mapping definition specifies the transformation for both: incoming and outgoing |
| messages.</p> |
| |
| <p>For example, to publish responses at the target address equal to the <code class="highlighter-rouge">reply-to</code> header of incoming commands, |
| define source header mapping and reply target as follows. If an incoming command does not have the <code class="highlighter-rouge">reply-to</code> header, |
| then its response is dropped.</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"reply-to"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:reply-to }}"</span><span class="w"> |
| </span><span class="p">},</span><span class="w"> |
| </span><span class="s2">"replyTarget"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:reply-to }}"</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>The reply target may contain its own header mapping (<code class="highlighter-rouge">"headerMapping"</code>) in order to map response headers.</p> |
| |
| <p>In addition, the reply target contains the expected response types (<code class="highlighter-rouge">"expectedResponseTypes"</code>) which should be |
| published to the reply target.<br /> |
| The following reply targets are available to choose from:</p> |
| <ul> |
| <li><strong>response</strong>: Send back successful responses (e.g. responses after a Thing was successfully modified, |
| but also responses for <a href="basic-signals-command.html#query-commands">query commands</a>). Includes positive <a href="protocol-specification-acks.html#acknowledgements-aggregating">acknowledgements</a>.</li> |
| <li><strong>error</strong>: Send back error responses (e.g. thing not modifiable due to lacking permissions)</li> |
| <li><strong>nack</strong>: If negative <a href="protocol-specification-acks.html#acknowledgements-aggregating">acknowledgement</a> responses should be delivered.</li> |
| </ul> |
| |
| <p>This is an example <code class="highlighter-rouge">"replyTarget"</code> containing both header mapping and expected response types:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"replyTarget"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:reply-to }}"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"correlation-id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:correlation-id }}"</span><span class="w"> |
| </span><span class="p">},</span><span class="w"> |
| </span><span class="s2">"expectedResponseTypes"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"response"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"error"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"nack"</span><span class="w"> |
| </span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h3 id="targets">Targets</h3> |
| |
| <p>Targets are used to connect to messages brokers / external systems in order to publish messages <strong>to them</strong>.</p> |
| |
| <p>Target messages can be of the following type:</p> |
| <ul> |
| <li><a href="basic-messages.html">messages</a></li> |
| <li><a href="basic-signals-event.html">events</a></li> |
| <li><a href="protocol-twinlive.html">live commands/responses/events</a></li> |
| </ul> |
| |
| <p>Targets contain:</p> |
| <ul> |
| <li>one address (that is interpreted differently depending on the <a href="#connection-types">connection type</a>, e.g. as queue, topic, etc.),</li> |
| <li><a href="#target-topics-and-filtering">topics</a> that will be sent to the target,</li> |
| <li>an authorization context (see <a href="#authorization">authorization</a>) specifying which <a href="basic-acl.html#authorization-subject">authorization subject</a> is used to authorize messages to the target, and</li> |
| <li><a href="connectivity-header-mapping.html">header mapping</a> to compute external headers from Ditto protocol headers.</li> |
| </ul> |
| |
| <h4 id="target-topics-and-filtering">Target topics and filtering</h4> |
| |
| <p>Which types of messages should be published to the target address, can be defined via configuration.</p> |
| |
| <p>In order to only consume specific events like described in <a href="basic-changenotifications.html">change notifications</a>, the |
| following parameters can additionally be provided when specifying the <code class="highlighter-rouge">topics</code> of a target:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Description</th> |
| <th>Topic</th> |
| <th><a href="basic-changenotifications.html#by-namespaces">Filter by namespaces</a></th> |
| <th><a href="basic-changenotifications.html#by-rql-expression">Filter by RQL expression</a></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Subscribe for <a href="basic-changenotifications.html">events/change notifications</a></td> |
| <td><code class="highlighter-rouge">_/_/things/twin/events</code></td> |
| <td>✔</td> |
| <td>✔</td> |
| </tr> |
| <tr> |
| <td>Subscribe for <a href="basic-messages.html">messages</a></td> |
| <td><code class="highlighter-rouge">_/_/things/live/messages</code></td> |
| <td>✔</td> |
| <td>❌</td> |
| </tr> |
| <tr> |
| <td>Subscribe for <a href="protocol-twinlive.html">live commands</a></td> |
| <td><code class="highlighter-rouge">_/_/things/live/commands</code></td> |
| <td>✔</td> |
| <td>❌</td> |
| </tr> |
| <tr> |
| <td>Subscribe for <a href="protocol-twinlive.html">live events</a></td> |
| <td><code class="highlighter-rouge">_/_/things/live/events</code></td> |
| <td>✔</td> |
| <td>✔</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>The parameters are specified similar to HTTP query parameters, the first one separated with a <code class="highlighter-rouge">?</code> and all following ones |
| with <code class="highlighter-rouge">&</code>. You need to URL-encode the filter values before using them in a configuration.</p> |
| |
| <p>For example, this way the connection session would register for all events in the namespace <code class="highlighter-rouge">org.eclipse.ditto</code> and which |
| would match an attribute “counter” to be greater than 42. Additionally it would subscribe to messages in the namespace |
| <code class="highlighter-rouge">org.eclipse.ditto</code>:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<target-address>"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"_/_/things/twin/events?namespaces=org.eclipse.ditto&filter=gt(attributes/counter,42)"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"_/_/things/twin/events?extraFields=attributes/placement&filter=gt(attributes/placement,'Kitchen')"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"_/_/things/live/messages?namespaces=org.eclipse.ditto"</span><span class="w"> |
| </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:outbound-auth-subject"</span><span class="p">,</span><span class="w"> </span><span class="s2">"..."</span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h4 id="target-topics-and-enrichment">Target topics and enrichment</h4> |
| |
| <div class="bs-callout bs-callout-primary">Available since Ditto <strong>1.1.0</strong></div> |
| |
| <p>When extra fields should be added to outgoing messages on a connection, an <code class="highlighter-rouge">extraFields</code> parameter can be added |
| to the topic. This is supported for all topics:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Description</th> |
| <th>Topic</th> |
| <th><a href="basic-enrichment.html">Enrich by extra fields</a></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Subscribe for <a href="basic-changenotifications.html">events/change notifications</a></td> |
| <td><code class="highlighter-rouge">_/_/things/twin/events</code></td> |
| <td>✔</td> |
| </tr> |
| <tr> |
| <td>Subscribe for <a href="basic-messages.html">messages</a></td> |
| <td><code class="highlighter-rouge">_/_/things/live/messages</code></td> |
| <td>✔</td> |
| </tr> |
| <tr> |
| <td>Subscribe for <a href="protocol-twinlive.html">live commands</a></td> |
| <td><code class="highlighter-rouge">_/_/things/live/commands</code></td> |
| <td>✔</td> |
| </tr> |
| <tr> |
| <td>Subscribe for <a href="protocol-twinlive.html">live events</a></td> |
| <td><code class="highlighter-rouge">_/_/things/live/events</code></td> |
| <td>✔</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>Example:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<target-address>"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"_/_/things/twin/events?extraFields=attributes/placement"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"_/_/things/live/messages?extraFields=features/ConnectionStatus"</span><span class="w"> |
| </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:outbound-auth-subject"</span><span class="p">,</span><span class="w"> </span><span class="s2">"..."</span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h4 id="target-issued-acknowledgement-label">Target issued acknowledgement label</h4> |
| |
| <p>A target can be configured to automatically <a href="basic-acknowledgements.html#issuing-acknowledgements">issue acknowledgements</a> |
| for each published/emitted message, once the underlying channel confirmed |
| that the message was successfully received.</p> |
| |
| <p>That is desirable whenever outgoing messages (e.g. <a href="basic-signals-event.html">events</a>) are handled in scope of a command |
| sent with an “at least once” (QoS 1) semantic in order to only acknowledge that command, if the event was successfully |
| forwarded into another system.</p> |
| |
| <p>For more details on that topic, please refer to the <a href="basic-acknowledgements.html">acknowledgements</a> section.</p> |
| |
| <p>Whether an outgoing message is treated as successfully sent or not is specific for the used |
| <a href="#connection-types">connection type</a> and documented in scope of that connection type.</p> |
| |
| <p>The JSON for a target with issued acknowledgement labels could look like this:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<target>"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"_/_/things/twin/events"</span><span class="w"> |
| </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"issuedAcknowledgementLabel"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-custom-ack"</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h4 id="target-header-mapping">Target header mapping</h4> |
| |
| <p>For outgoing messages, an optional <a href="connectivity-header-mapping.html">header mapping</a> may be applied. |
| Mapped headers are added to the external headers. |
| The default <a href="connectivity-mapping.html#ditto-mapper">Ditto payload mapper</a> does not define any external header; |
| in this case, all external headers come from the header mapping.</p> |
| |
| <p>The JSON for a target with header mapping could like this:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> |
| </span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<target>"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="s2">"_/_/things/twin/events"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"_/_/things/live/messages?namespaces=org.eclipse.ditto"</span><span class="w"> |
| </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"message-id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:correlation-id }}"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"content-type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:content-type }}"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"subject"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ topic:subject }}"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"reply-to"</span><span class="p">:</span><span class="w"> </span><span class="s2">"all-replies"</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h3 id="authorization">Authorization</h3> |
| |
| <p>A connection is initiated by the connectivity service. This obviates the need for client authorization, because |
| Ditto becomes the client in this case. Nevertheless, to access resources within Ditto, the connection must know on |
| whose behalf it is acting. This is controlled via the configured <code class="highlighter-rouge">authorizationContext</code>, which holds a list of |
| self-assigned authorization subjects. Before a connection can access a Ditto resource, one of its |
| <code class="highlighter-rouge">authorizationSubject</code>s must be granted the access rights by an authorization mechanism such as |
| <a href="basic-acl.html">ACLs</a> or <a href="basic-policy.html">Policies</a>.</p> |
| |
| <p>A connection target can only send data for things to which it has READ rights, as data flows from a thing to a target. |
| A connection source can only receive data for things to which it has WRITE rights, as data flows from a source to a thing.</p> |
| |
| <h3 id="specific-configuration">Specific configuration</h3> |
| |
| <p>Some <a href="#connection-types">connection types</a> require specific configuration, which is not supported for other connection types. |
| Those are put into the <code class="highlighter-rouge">specificConfig</code> field.</p> |
| |
| <h3 id="payload-mapping">Payload Mapping</h3> |
| |
| <p>For more information on mapping message payloads see the corresponding <a href="connectivity-mapping.html">Payload Mapping Documentation</a>.</p> |
| |
| <h2 id="placeholders">Placeholders</h2> |
| |
| <p>The configuration of a connection allows to use placeholders at certain places. This allows more fine-grained control |
| over how messages are consumed or where they are published to. The general syntax of a placeholder is |
| <code class="highlighter-rouge">{{ placeholder }}</code>. Have a look at the <a href="basic-placeholders.html">placeholders concept</a> for more details on that.</p> |
| |
| <h3 id="placeholder-for-source-authorization-subjects">Placeholder for source authorization subjects</h3> |
| |
| <p>Processing the messages received via a source using the <em>same fixed authorization subject</em> may not be |
| suitable for every scenario. For example, if you want to declare fine-grained write permissions per device, this would not |
| be possible with a fixed global subject. For this use case, we have introduced placeholder substitution for authorization subjects of |
| source addresses that are resolved when processing messages from a source. Of course, this requires the sender of the |
| message to provide necessary information about the original issuer of the message.</p> |
| |
| <div class="alert alert-warning" role="alert" style=""><i class="fa fa-warning"></i> <b>Important:</b> Only use this kind of placeholder if you trust the source of the message. The value from the header is used as the <strong>authorized subject</strong>.</div> |
| |
| <p>You can access any header value of the incoming message by using a placeholder like <code class="highlighter-rouge">{{ header:name }}</code>.</p> |
| |
| <p>Example:</p> |
| |
| <p>Assuming the messages received from the source <em>telemetry</em> contain a <code class="highlighter-rouge">device_id</code> header (e.g. <em>sensor-123</em>), |
| you may configure your source’s authorization subject as follows:</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth-subject-placeholder-example"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"sources"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"telemetry"</span><span class="w"> </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"device:{{ header:device_id }}"</span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| <p>The placeholder is then replaced by the value from the message headers and the message is forwarded and processed under the |
| subject <em>device:sensor-123</em>. |
| In case the header cannot be resolved or the header contains unexpected characters, an exception is thrown, which is sent |
| back to the sender as an error message, if a valid <em>reply-to</em> header was provided, otherwise the message is dropped.</p> |
| |
| <h3 id="placeholder-for-target-addresses">Placeholder for target addresses</h3> |
| |
| <p>Another use case for placeholders may be to publish twin events or live commands and events to a target address |
| containing thing-specific information e.g. you can distribute things from different namespaces to different target addresses. |
| You can use the placeholders <code class="highlighter-rouge">{{ thing:id }}</code>, <code class="highlighter-rouge">{{ thing:namespace }}</code> and <code class="highlighter-rouge">{{ thing:name }}</code> in the target address for this purpose. |
| For a thing with the ID <em>org.eclipse.ditto:device-123</em> these placeholders would be resolved as follows:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Placeholder</th> |
| <th>Description</th> |
| <th>Resolved value</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code class="highlighter-rouge">thing:id</code></td> |
| <td>Full ID composed of <em>namespace</em> <code class="highlighter-rouge">:</code> (as a separator), and <em>name</em></td> |
| <td><em>org.eclipse.ditto:device-123</em></td> |
| </tr> |
| <tr> |
| <td><code class="highlighter-rouge">thing:namespace</code></td> |
| <td>Namespace (i.e. first part of an ID)</td> |
| <td><em>org.eclipse.ditto</em></td> |
| </tr> |
| <tr> |
| <td><code class="highlighter-rouge">thing:name</code></td> |
| <td>Name (i.e. second part of an ID )</td> |
| <td><em>device-123</em></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>Additionally to the placeholders mentioned above, all documented |
| <a href="basic-placeholders.html#scope-connections">connection placeholders</a> may be |
| used in target addresses. However, if any placeholder in the target address fails to resolve, then the message will be |
| dropped.</p> |
| |
| <p>Example:</p> |
| |
| <p>Sending live commands and events to a target address that contains the thing’s namespace.</p> |
| <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w"> </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"target-placeholder-example"</span><span class="p">,</span><span class="w"> |
| </span><span class="s2">"targets"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> |
| </span><span class="p">{</span><span class="w"> |
| </span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"live/{{ thing:namespace }}"</span><span class="w"> </span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:auth-subject"</span><span class="p">],</span><span class="w"> |
| </span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"_/_/things/live/events"</span><span class="p">,</span><span class="w"> </span><span class="s2">"_/_/things/live/commands"</span><span class="w"> </span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span><span class="p">]</span><span class="w"> |
| </span><span class="p">}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| |
| <div class="tags"> |
| |
| <b>Tags: </b> |
| |
| |
| |
| <a href="tag_connectivity.html" class="btn btn-default navbar-btn cursorNorm" role="button">connectivity</a> |
| |
| |
| |
| </div> |
| |
| </div> |
| |
| <hr class="shaded"/> |
| |
| <footer> |
| <div class="row"> |
| <div class="col-lg-12 footer"> |
| <div class="logo"> |
| <a href="https://eclipse.org"><img src="images/eclipse_foundation_logo.svg" alt="Eclipse logo"/></a> |
| </div> |
| <p class="notice"> |
| ©2021 Eclipse Ditto. |
| Site last generated: Feb 22, 2021 <br /> |
| </p> |
| <div class="quickLinks"> |
| <a href="https://www.eclipse.org/legal/privacy.php" target="_blank"> |
| > Privacy Policy |
| </a> |
| <a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank"> |
| > Terms of Use |
| </a> |
| <a href="https://www.eclipse.org/legal/copyright.php" target="_blank"> |
| > Copyright Agent |
| </a> |
| <a href="https://www.eclipse.org/legal" target="_blank"> |
| > Legal |
| </a> |
| <a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank"> |
| > License |
| </a> |
| <a href="https://eclipse.org/security" target="_blank"> |
| > Report a Vulnerability |
| </a> |
| </div> |
| </div> |
| </div> |
| </footer> |
| |
| |
| </div> |
| <!-- /.row --> |
| </div> |
| <!-- /.container --> |
| </div> |
| <!-- /#main --> |
| </div> |
| |
| </body> |
| </html> |