URL:
https://<root>/data/find
Methods:
GET
Version Introduced:
12.2

Access requirements

Required privileges

The Server Administrator API requires privilege-based access. An administrator must be assigned a specific user privilege, or role, to access any given endpoint. Listed below are the user privileges or roles an administrator can be assigned that provides access to this endpoint. If multiple privileges are listed, only one needs to be assigned to gain access.



Note that administrators assigned a custom role must also have the administrative View all content privilege assigned to them to access the API directory as an administrator.

Tokens

This API requires token-based authentication. A token is automatically generated for administrators who sign in to the ArcGIS Server Administrator API directory's HTML interface. Tokens generated in this way are stored for the entirety of the session.

Those accessing the API directory outside of the HTML interface will need to acquire a session token from the ArcGIS Server Administrator API generateToken operation. For security reasons, all POST requests made to the ArcGIS Server Administrator API must include a token in the request body.


Learn how to generate a token

Description

The find operation searches ArcGIS Server for registered data store items that are either an exact or partial match to a provided data store JSON definition. This operation should be performed before registering a new data store item.

Understanding match results

This operation has a number of success responses that can be returned: an exact match, a partial match, and no match.

Exact match

An exact match is returned when the input data store definition matches with an already registered data store (i.e. an equivalent data store item). It is important to note that an exact match does not mean that the definition JSON and the equivalent data store have the exact same configuration. For example, they could have different item IDs, titles, descriptions, passwords, secret keys, and tokens and still be determined to be an exact match. The match criteria varies for each data store item type. For more information on the match criteria for each type, see the Match criteria section below. Exact matches can be returned for all data store item types.

When the response returns an exact match, users should evaluate the equivalent data store and determine whether it can be reused or modified.

Patrial match

A partial match is returned when the input data store definition lists a location that exists within an already existing data store item.

For example, if ArcGIS Server has a file share data store item that's registered with the followig path:

Use dark colors for code blocksCopy
1
\\machine1\data

and a member using this operation to check for any matching data stores uses a definition JSON that uses the following path:

Use dark colors for code blocksCopy
1
\\machine1\data\folder1

the find operation will return a partial match. This applies similarly to cloud store data items. If a cloud store with bucket1 as its objectStore location is registered with the server, and the find operation is provided a definition JSON for a new data store that has its objectStore location as bucket1\folder1, this operation will return a partial match.

Unlike an exact match, a partial match does not mean that the registered data item is considered to be an equivalent item, as the input definition and registered item may not have an equivalent configuration. When a partial match is returned, users should evaluate the input locations of both data store items. It is recommended that users do not move forward with registering a new data store item that uses a subfolder of an already registered path. Users should determine if the already registered data store item can be used or, if a new data store item needs to be registered, modify the definition JSON to use a unique path.

Partial matches are only applicable to file share and cloud store data store item types.

No match

The final possible success response type is an empty matches array, which is considered to be a "no match" response. A user that is not the data store item's owner, who has not had the item shared with them, and doesn't have the appropraite role or permissions to view the data store item may receive an empty array in their response JSON even if an exact or partial match does exist.

However, an empty array can also mean that there are no equivalent data store items, or partial matches, present on the server. In the event a user receives an empty array after performing this operation, time should be taken to determine whether the user has the appropriate permissions to view the data store or if the input JSON has no exact or partial matches.

Match criteria

The information used to evaluate whether the input definition JSON is an exact or partial match with a registered data store item varies depending on the data store type represented in the definition JSON. The table below outlines the data store item types supported by ArcGIS Enterprise, supported providers (if applicable), the match types they support (exact, partial, or both), as well as their match criteria.

Data store item typesProvidersMatch typeMatch criteria
Enterprise databases or cloud data warehouse
  • Oracle
  • PostgreSQL
  • Microsoft SQL Server
  • Google BigQuery
  • Amazon Redshift
  • Snowflake

Note: While Dameng, Db2, Elasticsearch, OpenSearch, and SAP HANA are supported in ArcGIS Enterprise, they are not currently supported by this operation.
Exact onlyDatabase-specific, non-secret identities
File sharesBoth exact and partialExact
  • Exact path matches (not case-sensitive)
  • For local file-system paths, the host identity must match

Partial
  • The input location exists within an already registered data store item
Cloud stores
  • Amazon Simple Storage Service (S3)
  • Microsoft Azure Blob Storage
  • Google Cloud storage
  • Alibaba Cloud Object Storage Service (OSS)
Both exact and partialExact
  • Provider
  • Credential type
  • Region information
  • Provider-specific account identity
  • Object store path

Partial
  • Hierarchical path partial matches
NoSQL and Graph data stores
  • ArangoDB
  • Neo4j
  • Amazon Neptune
Exact onlyNon-secret connection identity

Request parameters

ParameterDetails

inputDatastore

(Required)

A JSON object that represents a data store item definition. Though the properties included in the JSON object varies for each supported data store item type, the general structure of a data store item JSON object includes the following properties:

  • path—Defines a unique identifier for each data item when it's registered.
  • type—Describes the data item type.
  • info—A JSON object that contains the connection string or file system path to the data item.

For more information on the data item JSON object, and to see examples for different data store items, see the Register Item documentation.

f

The response format. The default format is html.

Values: html | json | pjson

Example usage

The following is a sample request for the find operation:

Use dark colors for code blocksCopy
1
https://organization.example.com/<context>/admin/data/find?inputDatastore={"path": "/fileShares/Test3DTiles_ds","type": "folder","info": {"isManaged": false,"path": "\\\\sample\\path\\desktop\\SceneLayers\\data\\3DTiles","dataStoreConnectionType": "shared"}}&f=JSON

JSON Response syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
{
  "matches": [ //Can be empty if no matches exist or if the user performing the operation doesn't have the appropriate permissions to view a matching data store
    {
      "itemId": "<data store item ID>",
      "matchType": "<exact | partial>"
    }
  ]
}

JSON Response examples

The following is a sample JSON response demonstrating a single exact match:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
{
  "matches": [
    {
      "itemId": "b3d252a4e2cc4cea83ff2149cd504e39",
      "matchType": "exact"
    }
  ]
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.