Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[http] Add thing config for User-Agent header #14518

Closed
wants to merge 1 commit into from
Closed

[http] Add thing config for User-Agent header #14518

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
131 changes: 66 additions & 65 deletions bundles/org.openhab.binding.http/README.md
View file
Open in desktop
Expand Up @@ -9,22 +9,23 @@ It can be extended with different channels.

## Thing Configuration

| parameter | optional | default | description |
|-------------------|----------|---------|-------------|
| `baseURL` | no | - | The base URL for this thing. Can be extended in channel-configuration. |
| `refresh` | no | 30 | Time in seconds between two refresh calls for the channels of this thing. |
| `timeout` | no | 3000 | Timeout for HTTP requests in ms. |
| `bufferSize` | no | 2048 | The buffer size for the response data (in kB). |
| `delay` | no | 0 | Delay between two requests in ms (advanced parameter). |
| `username` | yes | - | Username for authentication (advanced parameter). |
| `password` | yes | - | Password for authentication (advanced parameter). |
| `authMode` | no | BASIC | Authentication mode, `BASIC`, `BASIC_PREEMPTIVE` or `DIGEST` (advanced parameter). |
| `stateMethod` | no | GET | Method used for requesting the state: `GET`, `PUT`, `POST`. |
| `commandMethod` | no | GET | Method used for sending commands: `GET`, `PUT`, `POST`. |
| `contentType` | yes | - | MIME content-type of the command requests. Only used for `PUT` and `POST`. |
| `encoding` | yes | - | Encoding to be used if no encoding is found in responses (advanced parameter). |
| `headers` | yes | - | Additional headers that are sent along with the request. Format is "header=value". Multiple values can be stored as `headers="key1=value1", "key2=value2", "key3=value3",`. When using text based configuration include at minimum 2 headers to avoid parsing errors.|
| `ignoreSSLErrors` | no | false | If set to true ignores invalid SSL certificate errors. This is potentially dangerous.|
| parameter | optional | default | description |
| ----------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseURL` | no | - | The base URL for this thing. Can be extended in channel-configuration. |
| `refresh` | no | 30 | Time in seconds between two refresh calls for the channels of this thing. |
| `timeout` | no | 3000 | Timeout for HTTP requests in ms. |
| `bufferSize` | no | 2048 | The buffer size for the response data (in kB). |
| `delay` | no | 0 | Delay between two requests in ms (advanced parameter). |
| `username` | yes | - | Username for authentication (advanced parameter). |
| `password` | yes | - | Password for authentication (advanced parameter). |
| `authMode` | no | BASIC | Authentication mode, `BASIC`, `BASIC_PREEMPTIVE` or `DIGEST` (advanced parameter). |
| `stateMethod` | no | GET | Method used for requesting the state: `GET`, `PUT`, `POST`. |
| `commandMethod` | no | GET | Method used for sending commands: `GET`, `PUT`, `POST`. |
| `contentType` | yes | - | MIME content-type of the command requests. Only used for `PUT` and `POST`. |
| `encoding` | yes | - | Encoding to be used if no encoding is found in responses (advanced parameter). |
| `userAgent` | yes | - | The User-Agent header to send along with the request (advanced parameter). |
| `headers` | yes | - | Additional headers that are sent along with the request. Format is "header=value". Multiple values can be stored as `headers="key1=value1", "key2=value2", "key3=value3",`. When using text based configuration include at minimum 2 headers to avoid parsing errors. |
| `ignoreSSLErrors` | no | false | If set to true ignores invalid SSL certificate errors. This is potentially dangerous. |

_Note:_ Optional "no" means that you have to configure a value unless a default is provided and you are ok with that setting.

Expand All @@ -48,14 +49,14 @@ Depending on the channel-type, channels have different configuration options.
All channel-types (except `image`) have `stateExtension`, `commandExtension`, `stateTransformation`, `commandTransformation` and `mode` parameters.
The `image` channel-type supports `stateExtension`, `stateContent` and `escapedUrl` only.

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `stateExtension` | yes | - | Appended to the `baseURL` for requesting states. |
| `commandExtension` | yes | - | Appended to the `baseURL` for sending commands. If empty, same as `stateExtension`. |
| `stateTransformation` | yes | - | One or more transformation applied to received values before updating channel. |
| `commandTransformation` | yes | - | One or more transformation applied to channel value before sending to a remote. |
| `escapedUrl` | yes | - | This specifies whether the URL is already escaped. |
| `stateContent` | yes | - | Content for state requests (if method is `PUT` or `POST`) |
| parameter | optional | default | description |
| ----------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `stateExtension` | yes | - | Appended to the `baseURL` for requesting states. |
| `commandExtension` | yes | - | Appended to the `baseURL` for sending commands. If empty, same as `stateExtension`. |
| `stateTransformation` | yes | - | One or more transformation applied to received values before updating channel. |
| `commandTransformation` | yes | - | One or more transformation applied to channel value before sending to a remote. |
| `escapedUrl` | yes | - | This specifies whether the URL is already escaped. |
| `stateContent` | yes | - | Content for state requests (if method is `PUT` or `POST`) |
| `mode` | no | `READWRITE` | Mode this channel is allowed to operate. `READONLY` means receive state, `WRITEONLY` means send commands. |

Transformations need to be specified in the same format as
Expand All @@ -68,7 +69,7 @@ Transformations can be used if the supplied value (or the required value) is dif
Here are a few examples to unwrap an incoming value via `stateTransformation` from a complex response:

| Received value | Tr. Service | Transformation |
|---------------------------------------------------------------------|-------------|-------------------------------------------|
| ------------------------------------------------------------------- | ----------- | ----------------------------------------- |
| `{device: {status: { temperature: 23.2 }}}` | JSONPATH | `JSONPATH:$.device.status.temperature` |
| `<device><status><temperature>23.2</temperature></status></device>` | XPath | `XPath:/device/status/temperature/text()` |
| `THEVALUE:23.2°C` | REGEX | `REGEX::(.*?)°` |
Expand All @@ -80,74 +81,74 @@ The same mechanism works for commands (`commandTransformation`) for outgoing val

### `color`

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `onValue` | yes | - | A special value that represents `ON` |
| `offValue` | yes | - | A special value that represents `OFF` |
| `increaseValue` | yes | - | A special value that represents `INCREASE` |
| `decreaseValue` | yes | - | A special value that represents `DECREASE` |
| `step` | no | 1 | The amount the brightness is increased/decreased on `INCREASE`/`DECREASE` |
| `colorMode` | no | RGB | Mode for color values: `RGB` or `HSB` |
| parameter | optional | default | description |
| --------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `onValue` | yes | - | A special value that represents `ON` |
| `offValue` | yes | - | A special value that represents `OFF` |
| `increaseValue` | yes | - | A special value that represents `INCREASE` |
| `decreaseValue` | yes | - | A special value that represents `DECREASE` |
| `step` | no | 1 | The amount the brightness is increased/decreased on `INCREASE`/`DECREASE` |
| `colorMode` | no | RGB | Mode for color values: `RGB` or `HSB` |

All values that are not `onValue`, `offValue`, `increaseValue`, `decreaseValue` are interpreted as color value (according to the color mode) in the format `r,g,b` or `h,s,v`.

### `contact`

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `openValue` | no | - | A special value that represents `OPEN` |
| `closedValue` | no | - | A special value that represents `CLOSED` |
| parameter | optional | default | description |
| ------------- | -------- | ------- | ---------------------------------------- |
| `openValue` | no | - | A special value that represents `OPEN` |
| `closedValue` | no | - | A special value that represents `CLOSED` |

### `dimmer`

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `onValue` | yes | - | A special value that represents `ON` |
| `offValue` | yes | - | A special value that represents `OFF` |
| `increaseValue` | yes | - | A special value that represents `INCREASE` |
| `decreaseValue` | yes | - | A special value that represents `DECREASE` |
| `step` | no | 1 | The amount the brightness is increased/decreased on `INCREASE`/`DECREASE` |
| parameter | optional | default | description |
| --------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `onValue` | yes | - | A special value that represents `ON` |
| `offValue` | yes | - | A special value that represents `OFF` |
| `increaseValue` | yes | - | A special value that represents `INCREASE` |
| `decreaseValue` | yes | - | A special value that represents `DECREASE` |
| `step` | no | 1 | The amount the brightness is increased/decreased on `INCREASE`/`DECREASE` |

All values that are not `onValue`, `offValue`, `increaseValue`, `decreaseValue` are interpreted as brightness 0-100% and need to be numeric only.

### `number`

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `unit` | yes | - | The unit label for this channel |
| parameter | optional | default | description |
| --------- | -------- | ------- | ------------------------------- |
| `unit` | yes | - | The unit label for this channel |

`number` channels can be used for `DecimalType` or `QuantityType` values.
If a unit is given in the `unit` parameter, the binding tries to create a `QuantityType` state before updating the channel, if no unit is present, it creates a `DecimalType`.
Please note that incompatible units (e.g. `°C` for a `Number:Density` item) will fail silently, i.e. no error message is logged even if the state update fails.

### `player`

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `play` | yes | - | A special value that represents `PLAY` |
| `pause` | yes | - | A special value that represents `PAUSE` |
| `next` | yes | - | A special value that represents `NEXT` |
| `previous` | yes | - | A special value that represents `PREVIOUS` |
| `fastforward` | yes | - | A special value that represents `FASTFORWARD` |
| `rewind` | yes | - | A special value that represents `REWIND` |
| parameter | optional | default | description |
| ------------- | -------- | ------- | --------------------------------------------- |
| `play` | yes | - | A special value that represents `PLAY` |
| `pause` | yes | - | A special value that represents `PAUSE` |
| `next` | yes | - | A special value that represents `NEXT` |
| `previous` | yes | - | A special value that represents `PREVIOUS` |
| `fastforward` | yes | - | A special value that represents `FASTFORWARD` |
| `rewind` | yes | - | A special value that represents `REWIND` |

### `rollershutter`

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `upValue` | yes | - | A special value that represents `UP` |
| `downValue` | yes | - | A special value that represents `DOWN` |
| `stopValue` | yes | - | A special value that represents `STOP` |
| `moveValue` | yes | - | A special value that represents `MOVE` |
| parameter | optional | default | description |
| ----------- | -------- | ------- | -------------------------------------- |
| `upValue` | yes | - | A special value that represents `UP` |
| `downValue` | yes | - | A special value that represents `DOWN` |
| `stopValue` | yes | - | A special value that represents `STOP` |
| `moveValue` | yes | - | A special value that represents `MOVE` |

All values that are not `upValue`, `downValue`, `stopValue`, `moveValue` are interpreted as position 0-100% and need to be numeric only.

### `switch`

| parameter | optional | default | description |
|-------------------------|----------|-------------|-------------|
| `onValue` | no | - | A special value that represents `ON` |
| `offValue` | no | - | A special value that represents `OFF` |
| parameter | optional | default | description |
| ---------- | -------- | ------- | ------------------------------------- |
| `onValue` | no | - | A special value that represents `ON` |
| `offValue` | no | - | A special value that represents `OFF` |

**Note:** Special values need to be exact matches, i.e. no leading or trailing characters and comparison is case-sensitive.

Expand Down
4 changes: 4 additions & 0 deletions ...penhab.binding.http/src/main/java/org/openhab/binding/http/internal/HttpThingHandler.java
View file
Open in desktop
Expand Up @@ -329,6 +329,10 @@ private void sendHttpValue(String commandUrl, boolean escapedUrl, String command
}
}

if (config.userAgent != null) {
request.agent(config.userAgent);
}

config.headers.forEach(header -> {
String[] keyValuePair = header.split("=", 2);
if (keyValuePair.length == 2) {
Expand Down
1 change: 1 addition & 0 deletions ....binding.http/src/main/java/org/openhab/binding/http/internal/config/HttpThingConfig.java
View file
Open in desktop
Expand Up @@ -41,6 +41,7 @@ public class HttpThingConfig {

public @Nullable String encoding = null;
public @Nullable String contentType = null;
public @Nullable String userAgent = null;

public boolean ignoreSSLErrors = false;

Expand Down