External Location

View as Markdown

ExternalLocationInfo object

namestring: Name of the external location.

urlstring: Path URL of the external location.

credential_namestring: Name of the storage credential used with this location.

read_onlyboolean: Indicates whether the external location is read-only.

commentstring: User-provided free-form text description.

enable_file_eventsboolean: Whether to enable file events on this external location. Default to true. Set to false to disable file events. The actual applied value may differ due to server-side defaults; check effective_enable_file_events for the effective state.

file_event_queueobject

File event queue settings. If enable_file_events is not false, must be defined and have exactly one of the documented properties.

Examples:

{"provided_sqs":{"queue_url":"https://sqs.us-west-1.amazonaws.com/123456789012/test-queue"}} : Using a provided queue
{"managed_sqs":{}} : Using automatic queue creation

Show child attributesHide child attributes

provided_aqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_sqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_pubsubobject

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_aqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_sqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_pubsubobject

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

ownerstring: The owner of the external location.

encryption_detailsobject

Show child attributesHide child attributes

sse_encryption_detailsobject

Server-Side Encryption properties for clients communicating with AWS s3.

Show child attributesHide child attributes

algorithmstring: Sets the value of the 'x-amz-server-side-encryption' header in S3 request.
Values: SSE_ENCRYPTION_ALGORITHM_UNSPECIFIED, AWS_SSE_S3, AWS_SSE_KMS

aws_kms_key_arnstring: Optional. The ARN of the SSE-KMS key used with the S3 location, when algorithm = "SSE-KMS". Sets the value of the 'x-amz-server-side-encryption-aws-kms-key-id' header.

metastore_idstring: Unique identifier of metastore hosting the external location.

credential_idstring: Unique ID of the location's storage credential.

created_atint64: Time at which this external location was created, in epoch milliseconds.

created_bystring: Username of external location creator.

updated_atint64: Time at which external location this was last modified, in epoch milliseconds.

updated_bystring: Username of user who last modified the external location.

browse_onlyboolean: Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

isolation_modestring: Values: ISOLATION_MODE_UNSPECIFIED, ISOLATION_MODE_OPEN, ISOLATION_MODE_ISOLATED

fallbackboolean: Indicates whether fallback mode is enabled for this external location. When fallback mode is enabled, the access to the location falls back to cluster credentials if UC credentials are not sufficient.

effective_enable_file_eventsboolean: The effective value of enable_file_events after applying server-side defaults.

effective_file_event_queueobject

The effective file event queue configuration after applying server-side defaults. Always populated when a queue is provisioned, regardless of whether the user explicitly set enable_file_events. Use this field instead of file_event_queue for reading the actual queue state.

Show child attributesHide child attributes

provided_aqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_sqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_pubsubobject

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_aqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_sqsobject

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_pubsubobject

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

View as Markdown

The ExternalLocationInfo object

{
  "name": "string",
  "url": "string",
  "credential_name": "string",
  "read_only": true,
  "comment": "string",
  "enable_file_events": true,
  "file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  },
  "owner": "string",
  "encryption_details": {
    "sse_encryption_details": {}
  },
  "metastore_id": "string",
  "credential_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "browse_only": true,
  "isolation_mode": "string",
  "fallback": true,
  "effective_enable_file_events": true,
  "effective_file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  }
}

Get

GET /api/2.1/unity-catalog/external-locations/{name_arg}

Gets an external location from the metastore. The caller must be either a metastore admin, the owner of the external location, or a user that has some privilege on the external location.

API scopes: unity-catalog

Parameters

name_argstringpath: Name of the external location.

include_browsebooleanquery: Whether to include external locations in the response for which the principal can only access selective metadata for

Response

Returns the ExternalLocationInfo object.

View as Markdown

Response

{
  "name": "string",
  "url": "string",
  "credential_name": "string",
  "read_only": true,
  "comment": "string",
  "enable_file_events": true,
  "file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  },
  "owner": "string",
  "encryption_details": {
    "sse_encryption_details": {}
  },
  "metastore_id": "string",
  "credential_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "browse_only": true,
  "isolation_mode": "string",
  "fallback": true,
  "effective_enable_file_events": true,
  "effective_file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  }
}

List

GET /api/2.1/unity-catalog/external-locations

Gets an array of external locations (ExternalLocationInfo objects) from the metastore. The caller must be a metastore admin, the owner of the external location, or a user that has some privilege on the external location. There is no guarantee of a specific ordering of the elements in the array.

NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.

PAGINATION BEHAVIOR: When using pagination (max_results >= 0), a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters

include_browsebooleanquery: Whether to include external locations in the response for which the principal can only access selective metadata for

max_resultsint32query

Maximum number of external locations to return. If not set, all the external locations are returned (not recommended).

when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
when set to 0, the page length is set to a server configured value (recommended);
when set to a value less than 0, an invalid parameter error is returned;

Constraints: <= 1000

page_tokenstringquery: Opaque pagination token to go to next page based on previous query.

include_unboundbooleanquery: Whether to include external locations not bound to the workspace. Effective only if the user has permission to update the location–workspace binding.

Response

Returns a list of ExternalLocationInfo objects.

View as Markdown

Response

{
  "external_locations": [
    {
      "name": "string",
      "url": "string",
      "credential_name": "string",
      "read_only": true,
      "comment": "string",
      "enable_file_events": true,
      "file_event_queue": {},
      "owner": "string",
      "encryption_details": {},
      "metastore_id": "string",
      "credential_id": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "browse_only": true,
      "isolation_mode": "string",
      "fallback": true,
      "effective_enable_file_events": true,
      "effective_file_event_queue": {}
    }
  ],
  "next_page_token": "string"
}

Create

POST /api/2.1/unity-catalog/external-locations

Creates a new external location entry in the metastore. The caller must be a metastore admin or have the CREATE_EXTERNAL_LOCATION privilege on both the metastore and the associated storage credential.

API scopes: unity-catalog

Request body

skip_validationboolean: Skips validation of the storage credential associated with the external location.

namestring: Name of the external location.

urlstring: Path URL of the external location.

credential_namestring: Name of the storage credential used with this location.

read_onlyboolean: Indicates whether the external location is read-only.

commentstring: User-provided free-form text description.

enable_file_eventsboolean: Whether to enable file events on this external location. Default to true. Set to false to disable file events. The actual applied value may differ due to server-side defaults; check effective_enable_file_events for the effective state.

file_event_queueobject

File event queue settings. If enable_file_events is not false, must be defined and have exactly one of the documented properties.

Examples:

{"provided_sqs":{"queue_url":"https://sqs.us-west-1.amazonaws.com/123456789012/test-queue"}} : Using a provided queue
{"managed_sqs":{}} : Using automatic queue creation

Show child attributesHide child attributes

provided_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

ownerstring: The owner of the external location.

encryption_detailsobject

Show child attributesHide child attributes

sse_encryption_detailsobjectRequired

Server-Side Encryption properties for clients communicating with AWS s3.

Show child attributesHide child attributes

algorithmstring: Sets the value of the 'x-amz-server-side-encryption' header in S3 request.
Values: SSE_ENCRYPTION_ALGORITHM_UNSPECIFIED, AWS_SSE_S3, AWS_SSE_KMS

aws_kms_key_arnstring: Optional. The ARN of the SSE-KMS key used with the S3 location, when algorithm = "SSE-KMS". Sets the value of the 'x-amz-server-side-encryption-aws-kms-key-id' header.

metastore_idstring: Unique identifier of metastore hosting the external location.

credential_idstring: Unique ID of the location's storage credential.

created_atint64: Time at which this external location was created, in epoch milliseconds.

created_bystring: Username of external location creator.

updated_atint64: Time at which external location this was last modified, in epoch milliseconds.

updated_bystring: Username of user who last modified the external location.

browse_onlyboolean: Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

isolation_modestring: Values: ISOLATION_MODE_UNSPECIFIED, ISOLATION_MODE_OPEN, ISOLATION_MODE_ISOLATED

fallbackboolean: Indicates whether fallback mode is enabled for this external location. When fallback mode is enabled, the access to the location falls back to cluster credentials if UC credentials are not sufficient.

effective_enable_file_eventsboolean: The effective value of enable_file_events after applying server-side defaults.

effective_file_event_queueobject

Show child attributesHide child attributes

provided_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

Response

Returns the ExternalLocationInfo object.

View as Markdown

Request

{
  "skip_validation": true,
  "name": "string",
  "url": "string",
  "credential_name": "string",
  "read_only": true,
  "comment": "string",
  "enable_file_events": true,
  "file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  },
  "owner": "string",
  "encryption_details": {
    "sse_encryption_details": {}
  },
  "metastore_id": "string",
  "credential_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "browse_only": true,
  "isolation_mode": "string",
  "fallback": true,
  "effective_enable_file_events": true,
  "effective_file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  }
}

Response

{
  "name": "string",
  "url": "string",
  "credential_name": "string",
  "read_only": true,
  "comment": "string",
  "enable_file_events": true,
  "file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  },
  "owner": "string",
  "encryption_details": {
    "sse_encryption_details": {}
  },
  "metastore_id": "string",
  "credential_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "browse_only": true,
  "isolation_mode": "string",
  "fallback": true,
  "effective_enable_file_events": true,
  "effective_file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  }
}

Update

PATCH /api/2.1/unity-catalog/external-locations/{name_arg}

Updates an external location in the metastore. The caller must be the owner of the external location, or be a metastore admin. In the second case, the admin can only update the name of the external location.

API scopes: unity-catalog

Parameters

name_argstringpath: Name of the external location.

Request body

new_namestring: New name for the external location.

forceboolean: Force update even if changing url invalidates dependent external tables or mounts.

skip_validationboolean: Skips validation of the storage credential associated with the external location.

namestring: Name of the external location.

urlstring: Path URL of the external location.

credential_namestring: Name of the storage credential used with this location.

read_onlyboolean: Indicates whether the external location is read-only.

commentstring: User-provided free-form text description.

enable_file_eventsboolean: Whether to enable file events on this external location. Default to true. Set to false to disable file events. The actual applied value may differ due to server-side defaults; check effective_enable_file_events for the effective state.

file_event_queueobject

File event queue settings. If enable_file_events is not false, must be defined and have exactly one of the documented properties.

Examples:

{"provided_sqs":{"queue_url":"https://sqs.us-west-1.amazonaws.com/123456789012/test-queue"}} : Using a provided queue
{"managed_sqs":{}} : Using automatic queue creation

Show child attributesHide child attributes

provided_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

ownerstring: The owner of the external location.

encryption_detailsobject

Show child attributesHide child attributes

sse_encryption_detailsobjectRequired

Server-Side Encryption properties for clients communicating with AWS s3.

Show child attributesHide child attributes

algorithmstring: Sets the value of the 'x-amz-server-side-encryption' header in S3 request.
Values: SSE_ENCRYPTION_ALGORITHM_UNSPECIFIED, AWS_SSE_S3, AWS_SSE_KMS

aws_kms_key_arnstring: Optional. The ARN of the SSE-KMS key used with the S3 location, when algorithm = "SSE-KMS". Sets the value of the 'x-amz-server-side-encryption-aws-kms-key-id' header.

metastore_idstring: Unique identifier of metastore hosting the external location.

credential_idstring: Unique ID of the location's storage credential.

created_atint64: Time at which this external location was created, in epoch milliseconds.

created_bystring: Username of external location creator.

updated_atint64: Time at which external location this was last modified, in epoch milliseconds.

updated_bystring: Username of user who last modified the external location.

browse_onlyboolean: Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

isolation_modestring: Values: ISOLATION_MODE_UNSPECIFIED, ISOLATION_MODE_OPEN, ISOLATION_MODE_ISOLATED

fallbackboolean: Indicates whether fallback mode is enabled for this external location. When fallback mode is enabled, the access to the location falls back to cluster credentials if UC credentials are not sufficient.

effective_enable_file_eventsboolean: The effective value of enable_file_events after applying server-side defaults.

effective_file_event_queueobject

Show child attributesHide child attributes

provided_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

provided_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_aqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://{storage account}.queue.core.windows.net/{queue name} Only required for provided_aqs.

subscription_idstring: Optional subscription id for the queue, event grid subscription, and external location storage account. Required for locations with a service principal storage credential

resource_groupstring: Optional resource group for the queue, event grid subscription, and external location storage account. Only required for locations with a service principal storage credential

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_sqsobjectRequired

Show child attributesHide child attributes

queue_urlstring: The AQS queue url in the format https://sqs.{region}.amazonaws.com/{account id}/{queue name}. Only required for provided_sqs.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

managed_pubsubobjectRequired

Show child attributesHide child attributes

subscription_namestring: The Pub/Sub subscription name in the format projects/{project}/subscriptions/{subscription name}. Only required for provided_pubsub.

managed_resource_idstring: Unique identifier included in the name of file events managed cloud resources.

Response

Returns the ExternalLocationInfo object.

View as Markdown

Request

{
  "new_name": "string",
  "force": true,
  "skip_validation": true,
  "name": "string",
  "url": "string",
  "credential_name": "string",
  "read_only": true,
  "comment": "string",
  "enable_file_events": true,
  "file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  },
  "owner": "string",
  "encryption_details": {
    "sse_encryption_details": {}
  },
  "metastore_id": "string",
  "credential_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "browse_only": true,
  "isolation_mode": "string",
  "fallback": true,
  "effective_enable_file_events": true,
  "effective_file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  }
}

Response

{
  "name": "string",
  "url": "string",
  "credential_name": "string",
  "read_only": true,
  "comment": "string",
  "enable_file_events": true,
  "file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  },
  "owner": "string",
  "encryption_details": {
    "sse_encryption_details": {}
  },
  "metastore_id": "string",
  "credential_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "browse_only": true,
  "isolation_mode": "string",
  "fallback": true,
  "effective_enable_file_events": true,
  "effective_file_event_queue": {
    "provided_aqs": {},
    "provided_sqs": {},
    "provided_pubsub": {},
    "managed_aqs": {},
    "managed_sqs": {},
    "managed_pubsub": {}
  }
}

Delete

DELETE /api/2.1/unity-catalog/external-locations/{name_arg}

Deletes the specified external location from the metastore. The caller must be the owner of the external location.

API scopes: unity-catalog

Parameters

name_argstringpath: Name of the external location.

forcebooleanquery: Force deletion even if there are dependent external tables or mounts.