Update connector configuration API | Elasticsearch Guide [8.13]

› › ›

« Update connector API key ID API Update connector error API »

Update connector configuration APIedit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Updates a connector’s configuration, allowing for complete schema modifications or individual value updates within a registered configuration schema.

Requestedit

PUT _connector/<connector_id>/_configuration

Prerequisitesedit

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.

Path parametersedit

<connector_id>: (Required, string)

Request bodyedit

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.

Response codesedit

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.

Examplesedit

The following example updates the configuration for the connector with ID my-connector:

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.

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
        }
    }
}

{
    "result": "updated"
}

An example to update configuration values for the sharepoint_online connector:

PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "client_id": "my-client-id",
        "secret_value": "super-secret-value"
    }
}

{
    "result": "updated"
}

An example to update single configuration field of the sharepoint_online connector. In this case other configuration values won’t change:

PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "secret_value": "new-super-secret-value"
    }
}

{
    "result": "updated"
}

« Update connector API key ID API Update connector error API »