- URL:
- https://<root>/data/registerItem
- Methods:
POST
- Required Capability:
- Access allowed with either the "Security and Infrastructure", "Server", or "Register data stores" privileges, or the Publisher role
- Version Introduced:
- 10.1
Description
The register
operation registers a new data item with the server's data store by submitting a JSON object that represents the data item and its connection information.
A data item contains all the information required by ArcGIS Server to connect to a folder or database while serving out one or more GIS services. Data items are extensively used while publishing GIS services to ArcGIS Server, as they inform the publishing client (such as ArcGIS Pro) whether the data needs to be explicitly copied to the server or whether it can be referred from the server. ArcGIS Server supports the following types of data items:
- Enterprise databases—Each of these data items represents an enterprise database, which can optionally contain an Esri geodatabase.
- Big data file shares—Deprecated at 11.4. Big data file share data items are network-accessible file system folders, Apache Hadoop Distributed File System (HDFS) or Apache Hive stores, or cloud stores that contain one or more datasets. Big data file share items are the inputs to analysis using GeoAnalytics Server.
- Cloud stores—Cloud store data items represent a connection to an Amazon or Microsoft Azure store.
- Object store—Starting at 11.4, an object store is required as part of the base deployment for ArcGIS Enterprise. Organizations deploying ArcGIS Enterprise using Amazon Web Serivces (AWS) should deploy an object store using Amazon S3. Organizations deploying ArcGIS Enterprise using Microsoft Azure should deploy an object store using Azure Blob Storage.
- Raster stores—These are network-accessible file system folders or cloud stores that are output stores for raster analysis.
- File shares—File share data items are network-accessible file system folders that contain one or more datasets.
Before registering the data item, you must validate it and make sure that it is accessible from all the server nodes in your site.
Registration requirements
The following sections outline the connection information for each supported data item type.
Enterprise databases
For enterprise geodatabases, you must provide the connection
property as part of the info
JSON object. The connection string consists of information such as the name of the database server, the database name, and the credentials. ArcGIS Server will store the data item's JSON information in its configuration store as is. As such, it is recommended that you encrypt the credentials before registering an enterprise geodatabase data item by using the encryption scheme in the Get Database Connection String tool in the Publishing Tools toolbox, which can be found by accessing the HTML view of the Services Directory API and navigating to System > System/PublishingTools > Get Database Connection String > Submit Job, or by making a request of the following form:
https://machine.domain.com/webadaptor/rest/services/System/PublishingTools/GPServer/Get%20Database%20Connection%20String/submitJob
The string returned by the Get Database Connection String tool can be used as the value for the connection
property.
To see sample cloud store data item JSON objects, see the Enterprise database info examples section below.
Big data file shares
Big data file share data items can be file shares, HDFS, Hive, or cloud data stores that contain input data for GeoAnalytics.
The following items should be taken into consideration while registering a big data file share data item:
- The
connection
property represents the type of big data file share item. Possible values areType file
,Share hdfs
,hive
, andcloudstore
. - The
username
property is optional for HDFS and Hive file shares.
Example JSON objects for big data file share data items can be viewed in the API installed help for organizations at version 11.3 or earlier.
Cloud stores
Cloud store data items represent a connection to an Amazon or Microsoft Azure store. Connection information for the data store item is stored as a JSON string in the connection
.
The following items should be taken into consideration while registering a cloud store data item:
- A valid value for the
objectstore
parameter is required. This property refers to the Amazon S3 bucket, Azure Blob container or Azure Data Lake store, Alibaba OSS bucket or Google cloud container. - Folders in an object store property are optional.
To see sample cloud store data item JSON objects, see the Cloud store examples section below.
Object store
An object store is part of an ArcGIS Enterprise base deployment that can either be provided by ArcGIS Data Store or provided by Amazon S3 or Azure Blob Storage for organizations that deploy ArcGIS Enterprise using Amazon Web Serivces (AWS) or Microsoft Azure. An organization only supports having one object store registered. Attempting to do any of the following will result in the register
operation to fail:
- Register a cloud-provided object store when an ArcGIS Data Store object store is already registered
- Register another cloud-provided object store when a cloud-provided object store is already registered
- Register an ArcGIS Data Store object store when a cloud-provided object store is already registered
The Object store examples section below demonstrates all of the required properties to register a cloud-provided object store. The only optional property value is folder
.
Raster stores
Raster store items are network-accessible file system folders or cloud stores that are output stores for raster analysis.
When registering a raster store data item, the connection
value for a raster store data store item can either be specified as a file
or data
.
To see sample cloud store data item JSON objects, see the Raster store info examples section below.
Request parameters
Parameter | Details |
---|---|
| A JSON object that represents the data item. Though each data store item type has unique requirements, the general structure of a data store item JSON object includes the following properties:
|
| The response format. The default response format is Values: |
Info properties
Parameter | Details |
---|---|
| The file system path to the data item. |
| The connection string for client to connect to shared enterprise database. |
| The connection string for ArcGIS Server to connect to enterprise database. |
| Indicates to ArcGIS Server whether the data item is If If If |
| Set to Values: |
Example usage
The following is a sample POST request for the register
operation that demonstrates registering a big data file share data item, formatted for readability:
POST /webadaptor/admin/data/registerItem HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
item={
"path": "/bigDataFileShares/myFileShare",
"type": "bigDataFileShare",
"info": {
"connectionString": "{\"path\":\"\\\\\\\\myFileShare\\\\data\\\\geoanalytics\"}", //backslashes in path should be double escaped.
"connectionType": "fileShare"
}
}&f=pjson
Enterprise database examples
The example below demonstrates a sample JSON object for an enterprise geodatabase data item that has the publisher and ArcGIS Server using the same database:
{
"path": "/enterpriseDatabases/egdb_shared", //a unique path on the server
"type": "egdb", //as this is a database
"clientPath": null, //not needed as this is a database
"info": {
"connectionString": "ENCRYPTED_PASSWORD=00022e686f66464c762b6e2b31732b675a4e35667832547070513d3d2a00;SERVER=dbserver;INSTANCE=sde:sqlserver:dbserver;DBCLIENT=sqlserver;DB_CONNECTION_PROPERTIES=dbserver;DATABASE=vtest;USER=map;VERSION=sde.DEFAULT;AUTHENTICATION_MODE=DBMS", //an encrypted connection string
"isManaged": false, //indicates that the database is not fully owned by the server
"dataStoreConnectionType": "shared" //indicates that the database is shared with clients
}
}
Cloud store examples
Amazon S3
The example below demonstrates a sample JSON object for an Amazon S3 cloud store that uses access key authentication:
{
"path": "/cloudStores/<value>",
"type": "cloudStore",
"provider": "amazon",
"info": {
"objectStore": "<bucketName>/<folderName>",
"connectionString": "{\"credentialType\":\"accessKey\",\"accessKeyId\":\"<value>\",\"secretAccessKey\":\"<value>\",\"regionEndpointUrl\":\"s3.us-west-2.amazonaws.com\",\"region\":\"us-west-2\",\"defaultEndpointsProtocol\": \"https\"}"
}
}
Azure Blob
The example below demonstrates a sample JSON object for a public Microsoft Azure cloud store that uses shared key (account
) authentication:
{
"path": "/cloudStores/<value>",
"type": "cloudStore",
"provider": "azure",
"info": {
"objectStore": "<containerName>/<folderName>",
"connectionString": "{\"accountKey\":\"<value>\",\"accountName\":\"<value>\",\"defaultEndpointsProtocol\":\"https\",\"accountEndpoint\":\"core.windows.net\",\"credentialType\":\"accessKey\"}"
}
}
The example below demonstrates a sample JSON object for a Microsoft Azure cloud store with private endpoint access that uses shared key (account
) authentication:
{
"path": "/cloudStores/<value>",
"type": "cloudStore",
"provider": "azure",
"info": {
"objectStore": "<containerName>/<folderName>",
"connectionString": "{\"credentialType\":\"accessKey\",\"accountKey\":\"<value>\",\"regionEndpointUrl\":\"<value>\",\"defaultEndpointsProtocol\":\"https\"}"
}
}
Azure Data Lake Gen2
Support for Azure Data Lake Gen2 cloud store data items was added at ArcGIS Enterprise 11.1.
The example below demonstrates a sample JSON object for an Azure Data Lake Gen2 cloud store that uses shared key (account
) authentication:
{
"path": "/cloudStores/<value>",
"type": "cloudStore",
"provider": "azureDataLakeStore",
"info": {
"isManaged": false,
"connectionString": "{\"credentialType\":\"accesskey\",\"accountKey\":\"<value>\",\"accountName\":\"<value>\",\"accountEndpoint\":\"core.windows.net\"}",
"folder": "<containerName>/<folderName>"
}
}
Google
The example below demonstrates a sample JSON object for a Google cloud store data item:
{
"path": "/cloudStores/<value>",
"type": "cloudStore",
"provider": "google",
"info": {
"isManaged": false,
"connectionString": "{\"accessKeyId\":\"<value>\",\"secretAccessKey\":\"<value>\",\"regionEndpointUrl\":\"storage.googleapis.com\",\"defaultEndpointsProtocol\":\"https\",\"credentialType\":\"accesskey\"}",
"objectStore": "<bucketName>/<folderName>"
}
}
Alibaba
The example below demonstrates a sample JSON object an Alibaba cloud store data item:
{
"path": "/cloudStores/<value>",
"type": "cloudStore",
"systemManaged": false,
"provider": "Alibaba",
"info": {
"isManaged": false,
"connectionString": "{\"accessKeyId\":\"<value>\",\"secretAccessKey\":\"<value>\",\"regionEndpointUrl\":\"oss-us-west-1.aliyuncs.com\",\"defaultEndpointsProtocol\":\"https\",\"credentialType\":\"accesskey\"}",
"objectStore": "<bucketName>/<folderName>"
}
}
Object store examples
Amazon S3
The example below demonstrates a sample JSON object for an Amazon S3 cloud-provided object store that uses access key authentication:
{
"path": "/cloudStores/<value>",
"type": "objectStore",
"provider": "amazon",
"info": {
"isManaged": true,
"systemManaged": false,
"isManagedData": true,
"purposes": [
"feature-tile",
"scene"
],
"connectionString": "{\"accessKeyId\":\"<AccessKeyValue>\",\"secretAccessKey\":\"<SecretValue>\",\"regionEndpointUrl\":\"<RegionURL>\",\"defaultEndpointsProtocol\":\"https\",\"credentialType\":\"accesskey\",\"region\":\"<RegionID>\"}",
"objectStore": "<bucketName>/<folder_name>"
}
}
Azure Blob
The example below demonstrates a sample JSON object for a Microsoft Azure cloud-provided object store that uses shared key (account
) authentication:
{
"path": "/cloudStores/<value>",
"type": "objectStore",
"provider": "azure",
"info": {
"isManaged": true,
"systemManaged": false,
"isManagedData": true,
"purposes": [
"feature-tile",
"scene"
],
"objectStore": "<containerName>/<folderName>",
"connectionString": "{\"accountKey\":\"<value>\",\"accountName\":\"<value>\",\"defaultEndpointsProtocol\":\"https\",\"accountEndpoint\":\"core.windows.net\",\"credentialType\":\"accessKey\"}"
}
}
Raster store examples
The example below demonstrates a sample JSON object for a raster store data item with a file
connection type:
{
"path": "/rasterStores/rasterstore_fileshare",
"type": "rasterStore",
"info": {
"connectionString": "{\"path\":\"\\\\\\\\myserver\\\\data\"}", //backslashes in path should be double escaped.
"connectionType": "fileShare"
}
}
File share examples
The example below demonstrates a sample JSON object for a file share data item where the folder for the publisher and ArcGIS Server use the same shared path:
{
"path": "/fileShares/folder_shared", //a unique path on the server
"type": "folder", //as this is a file share
"clientPath": null, //not needed as this is a shared folder
"info": {
"path": "\\\\server\\data\\rest_data", //path to the share
"dataStoreConnectionType": "shared" //this is a shared folder
}
}
JSON Response example
{"status": "success"}