mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
249 lines
9.1 KiB
Text
249 lines
9.1 KiB
Text
[[update-connector-configuration-api]]
|
|
=== Update connector configuration API
|
|
++++
|
|
<titleabbrev>Update connector configuration</titleabbrev>
|
|
++++
|
|
|
|
preview::[]
|
|
|
|
Updates a connector's `configuration`, allowing for complete schema modifications or individual value updates within a registered configuration schema.
|
|
|
|
|
|
[[update-connector-configuration-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT _connector/<connector_id>/_configuration`
|
|
|
|
[[update-connector-configuration-api-prereq]]
|
|
==== {api-prereq-title}
|
|
|
|
* To sync data using connectors, it's essential to have the Elastic connectors service running.
|
|
* The `connector_id` parameter should reference an existing connector.
|
|
* The configuration fields definition must be compatible with the specific connector type being used.
|
|
|
|
[[update-connector-configuration-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<connector_id>`::
|
|
(Required, string)
|
|
|
|
[role="child_attributes"]
|
|
[[update-connector-configuration-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`values`::
|
|
(Optional, object) Configuration values for the connector, represented as a mapping of configuration fields to their respective values within a registered schema.
|
|
|
|
`configuration`::
|
|
(Optional, object) The configuration for the connector. The configuration field is a map where each key represents a specific configuration field name, and the value is a `ConnectorConfiguration` object.
|
|
|
|
Each `ConnectorConfiguration` object contains the following attributes:
|
|
|
|
* `category` (Optional, string) The category of the configuration field. This helps in grouping related configurations together in the user interface.
|
|
|
|
* `default_value` (Required, string | number | bool) The default value for the configuration. This value is used if the value field is empty, applicable only for non-required fields.
|
|
|
|
* `depends_on` (Required, array of `ConfigurationDependency`) An array of dependencies on other configurations. A field will not be enabled unless these dependencies are met. Each dependency specifies a field key and the required value for the dependency to be considered fulfilled.
|
|
|
|
* `display` (Required, string) The display type for the UI element that represents this configuration. This defines how the field should be rendered in the user interface. Supported types are: `text`, `textbox`, `textarea`, `numeric`, `toggle` and `dropdown`.
|
|
|
|
* `label` (Required, string) The display label for the configuration field. This label is shown in the user interface, adjacent to the field.
|
|
|
|
* `options` (Required, array of `ConfigurationSelectOption`) An array of options for list-type fields. These options are used for inputs in the user interface, each having a label for display and a value.
|
|
|
|
* `order` (Required, number) The order in which this configuration appears in the user interface. This helps in organizing fields logically.
|
|
|
|
* `placeholder` (Required, string) Placeholder text for the configuration field. This text is displayed inside the field before a value is entered.
|
|
|
|
* `required` (Required, boolean) Indicates whether the configuration is mandatory. If true, a value must be provided for the field.
|
|
|
|
* `sensitive` (Required, boolean) Indicates whether the configuration contains sensitive information. Sensitive fields may be obfuscated in the user interface.
|
|
|
|
* `tooltip` (Optional, string) Tooltip text providing additional information about the configuration. This text appears when the user hovers over the info icon next to the configuration field.
|
|
|
|
* `type` (Required, string) The type of the configuration field, such as `str`, `int`, `bool`, `list`. This defines the data type and format of the field's value.
|
|
|
|
* `ui_restrictions` (Required, array of strings) A list of UI restrictions. These restrictions define where in the user interface this field should be available or restricted.
|
|
|
|
* `validations` (Required, array of `ConfigurationValidation`) An array of rules for validating the field's value. Each validation specifies a type and a constraint that the field's value must meet.
|
|
|
|
* `value` (Required, string | number | bool) The current value of the configuration. This is the actual value set for the field and is used by the connector during its operations.
|
|
|
|
`ConfigurationDependency` represents a dependency that a configuration field has on another field's value. It contains the following attributes:
|
|
|
|
* `field` (Required, string) The name of the field in the configuration that this dependency relates to.
|
|
|
|
* `value` (Required, string | number | bool) The required value of the specified field for this dependency to be met.
|
|
|
|
`ConfigurationSelectOption` defines an option within a selectable configuration field. It contains the following attributes:
|
|
|
|
* `label` (Required, string) The display label for the option.
|
|
|
|
* `value` (Required, string) The actual value associated with the option.
|
|
|
|
`ConfigurationValidation` specifies validation rules for configuration fields. Each ConfigurationValidation instance enforces a specific type of validation based on its type and constraint. It contains the following attributes:
|
|
|
|
* `constraint` (Required, string | number) The validation constraint. The nature of this constraint depends on the validation type. It could be a numeric value, a list, a regular expression pattern.
|
|
|
|
* `type` (Required, ConfigurationValidationType) The type of validation to be performed. Possible values include: `less_than`, `greater_than`, `list_type`, `included_in`, `regex` and `unset`.
|
|
|
|
|
|
[[update-connector-configuration-api-response-codes]]
|
|
==== {api-response-codes-title}
|
|
|
|
`200`::
|
|
Connector configuration was successfully updated.
|
|
|
|
`400`::
|
|
The `connector_id` was not provided or the request payload was malformed.
|
|
|
|
`404` (Missing resources)::
|
|
No connector matching `connector_id` could be found.
|
|
|
|
[[update-connector-configuration-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example updates the `configuration` for the connector with ID `my-connector`:
|
|
|
|
////
|
|
[source, console]
|
|
--------------------------------------------------
|
|
PUT _connector/my-spo-connector
|
|
{
|
|
"index_name": "search-sharepoint-online",
|
|
"name": "Sharepoint Online Connector",
|
|
"service_type": "sharepoint_online"
|
|
}
|
|
|
|
PUT _connector/my-spo-connector/_configuration
|
|
{
|
|
"configuration": {
|
|
"client_id": {
|
|
"default_value": null,
|
|
"depends_on": [],
|
|
"display": "text",
|
|
"label": "Client ID",
|
|
"options": [],
|
|
"order": 3,
|
|
"required": true,
|
|
"sensitive": false,
|
|
"tooltip": null,
|
|
"type": "str",
|
|
"ui_restrictions": [],
|
|
"validations": [],
|
|
"value": null
|
|
},
|
|
"secret_value": {
|
|
"default_value": null,
|
|
"depends_on": [],
|
|
"display": "text",
|
|
"label": "Secret value",
|
|
"options": [],
|
|
"order": 4,
|
|
"required": true,
|
|
"sensitive": true,
|
|
"tooltip": null,
|
|
"type": "str",
|
|
"ui_restrictions": [],
|
|
"validations": [],
|
|
"value": null
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE _connector/my-spo-connector
|
|
--------------------------------------------------
|
|
// TEARDOWN
|
|
////
|
|
|
|
This example demonstrates how to register a `sharepoint_online` connector configuration schema. Note: The example does not cover all the necessary configuration fields for operating the Sharepoint Online connector.
|
|
|
|
[source,console]
|
|
----
|
|
PUT _connector/my-spo-connector/_configuration
|
|
{
|
|
"configuration": {
|
|
"client_id": {
|
|
"default_value": null,
|
|
"depends_on": [],
|
|
"display": "text",
|
|
"label": "Client ID",
|
|
"options": [],
|
|
"order": 3,
|
|
"required": true,
|
|
"sensitive": false,
|
|
"tooltip": null,
|
|
"type": "str",
|
|
"ui_restrictions": [],
|
|
"validations": [],
|
|
"value": null
|
|
},
|
|
"secret_value": {
|
|
"default_value": null,
|
|
"depends_on": [],
|
|
"display": "text",
|
|
"label": "Secret value",
|
|
"options": [],
|
|
"order": 4,
|
|
"required": true,
|
|
"sensitive": true,
|
|
"tooltip": null,
|
|
"type": "str",
|
|
"ui_restrictions": [],
|
|
"validations": [],
|
|
"value": null
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"result": "updated"
|
|
}
|
|
----
|
|
|
|
An example to update configuration values for the `sharepoint_online` connector:
|
|
|
|
[source,console]
|
|
----
|
|
PUT _connector/my-spo-connector/_configuration
|
|
{
|
|
"values": {
|
|
"client_id": "my-client-id",
|
|
"secret_value": "super-secret-value"
|
|
}
|
|
}
|
|
----
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"result": "updated"
|
|
}
|
|
----
|
|
|
|
|
|
An example to update single configuration field of the `sharepoint_online` connector. In this case other configuration values won't change:
|
|
|
|
[source,console]
|
|
----
|
|
PUT _connector/my-spo-connector/_configuration
|
|
{
|
|
"values": {
|
|
"secret_value": "new-super-secret-value"
|
|
}
|
|
}
|
|
----
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"result": "updated"
|
|
}
|
|
----
|