IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Set connector sync job stats API Update connector error API »
Elastic Docs ›Elasticsearch Guide [8.12] ›REST APIs ›Connector APIs

Update connector configuration API

edit

Update connector configuration API

edit

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 the configuration of a connector.

Request

edit

PUT _connector/<connector_id>/_configuration

Prerequisites

edit
  • 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 parameters

edit
<connector_id>
(Required, string)

Request body

edit
configuration
(Required, 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 codes

edit
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.

Examples

edit

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

response = client.connector.update_configuration(
  connector_id: 'my-connector',
  body: {
    configuration: {
      service_account_credentials: {
        default_value: nil,
        depends_on: [],
        display: 'textarea',
        label: 'Google Drive service account JSON',
        options: [],
        order: 1,
        required: true,
        sensitive: true,
        tooltip: 'This connectors authenticates as a service account to synchronize content from Google Drive.',
        type: 'str',
        ui_restrictions: [],
        validations: [],
        value: '...service account JSON...'
      }
    }
  }
)
puts response
PUT _connector/my-connector/_configuration
{
    "configuration": {
        "service_account_credentials": {
            "default_value": null,
            "depends_on": [],
            "display": "textarea",
            "label": "Google Drive service account JSON",
            "options": [],
            "order": 1,
            "required": true,
            "sensitive": true,
            "tooltip": "This connectors authenticates as a service account to synchronize content from Google Drive.",
            "type": "str",
            "ui_restrictions": [],
            "validations": [],
            "value": "...service account JSON..."
        }
    }
}
{
    "result": "updated"
}
« Set connector sync job stats API Update connector error API »