- 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 generate operation. For security reasons, all POST requests made to the ArcGIS Server Administrator API must include a token in the request body.
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:
\\machine1\dataand a member using this operation to check for any matching data stores uses a definition JSON that uses the following path:
\\machine1\data\folder1the find operation will return a partial match. This applies similarly to cloud store data items. If a cloud store with bucket1 as its object location is registered with the server, and the find operation is provided a definition JSON for a new data store that has its object 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 types | Providers | Match type | Match criteria |
|---|---|---|---|
| Enterprise databases or cloud data warehouse |
Note: While Dameng, Db2, Elasticsearch, OpenSearch, and SAP HANA are supported in ArcGIS Enterprise, they are not currently supported by this operation. | Exact only | Database-specific, non-secret identities |
| File shares | Both exact and partial | Exact
Partial
| |
| Cloud stores |
| Both exact and partial | Exact
Partial
|
| NoSQL and Graph data stores |
| Exact only | Non-secret connection identity |
Request parameters
| Parameter | Details |
|---|---|
(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:
For more information on the data item JSON object, and to see examples for different data store items, see the Register Item documentation. |
| The response format. The default format is Values: |
Example usage
The following is a sample request for the find operation:
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=JSONJSON Response syntax
{
"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:
{
"matches": [
{
"itemId": "b3d252a4e2cc4cea83ff2149cd504e39",
"matchType": "exact"
}
]
}