Register Item | ArcGIS REST APIs

URL:: https://<root>/data/registerItem
Methods:: POST
Version Introduced:: 12.0

Description

The registerItem 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 Video Server to connect to a folder or database while serving out one or more video services. Data items are extensively used while publishing video services to ArcGIS Video Server, as they inform the publishing client (such as ArcGIS Excalibur or ArcGIS Pro) whether the data needs to be explicitly copied to the server or whether it can be referred from the server. ArcGIS Video Server supports the following types of data items:

Spatiotemporal Big Data Stores—Spatiotemporal Big Data Stores are required for the REST API's Search operation to function correctly. Services can be registered to this data store by administrators.
Cloud stores—Cloud store data items represent a connection to an Amazon or Microsoft Azure store.
Object stores—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.
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.

Spatiotemporal big data stores

The spatiotemporal big data store enables archival of high volume observation data, sustains high velocity write throughput, and can run across multiple machines (nodes). Adding additional machines adds capacity, enabling you to store more data, implement longer retention policies of your data, and support higher data write throughput.

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

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 registerItem operation to fail:

The Object store examples section below demonstrates all of the required properties to register a cloud-provided object store.

Request parameters

Parameter Details

Parameter	Details
`item`	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: `path`—Defines a unique identifier for each data item when it's registered with ArcGIS Video Server. `type`—Describes the type of the data item. `info`—A JSON object that contains the connection string or file system path to the data item. For more information on the properties included in the `info` JSON object, see the Info properties section below.
`f` (Required)	The response format. The default response format is `html`. Values: `html` \| `json` \| `pjson`
`token` (Required)	Users interacting programmatically with this endpoint must generate a token that must be included as a request parameter. A token can be obtained using the Generate Token operation.

item

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:

path—Defines a unique identifier for each data item when it's registered with ArcGIS Video Server.
type—Describes the type of the data item.
info—A JSON object that contains the connection string or file system path to the data item. For more information on the properties included in the info JSON object, see the Info properties section below.

f

(Required)

The response format. The default response format is html.

Values: html | json | pjson

token

(Required)

Users interacting programmatically with this endpoint must generate a token that must be included as a request parameter. A token can be obtained using the Generate Token operation.

Response properties

Property	Details
`path`	The file system path to the data item.
`clientConnectionString`	The connection string for client to connect to shared enterprise database.
`connectionString`	The connection string for ArcGIS Video Server to connect to enterprise database. Note The connection information for big data file share, cloud store, and raster store data items is encrypted by ArcGIS Video Server and stored in the `connectionString` property as a JSON string. Encrypted information is denoted by a `{crypt}` prefix.
`dataStoreConnectionType`	Indicates to ArcGIS Video Server whether the data item is `shared`, `replicated`, or `server` only. If `shared`, the publisher (for example, ArcGIS Pro) and server use the same connection string to the database and point to the same instance of the database. If `replicated`, the publisher and server connect to different instances of the database that have the same copies of the data because their replication configurations or administrative scripts keep them in sync. If `serverOnly`, the database is entirely managed and owned by ArcGIS Video Server and cannot be accessed by the publisher directly. This option is primarily used to refer to an ArcGIS Video Server Managed Database.
`isManaged`	Set to `true` if `dataStoreConnectionType` is set as `server`, indicating that the data store is managed by ArcGIS Video Server. Otherwise, `isManaged` is set to `false`. Values: `true` \| `false`

Example usage

The following is a sample POST request for the registerItem operation that demonstrates registering a file share data item, formatted for readability:

Use dark colors for code blocksCopy
POST /<context>/admin/data/registerItem HTTP/1.1
Host: organization.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

item={
  "path": "/folder/myFileShare",
  "type": "folderFileShare",
  "info": {
    "connectionString": "{\"path\":\"\\\\\\\\myFileShare\\\\data\"}", //backslashes in path should be double escaped.
    "connectionType": "fileShare"
  }
}&f=pjson

Spatiotemporal Big Data Store example

The example below demonstrates a sample JSON object for a spatiotremporal big data store "ozone" data item:

Use dark colors for code blocksCopy
{
  "path": "/nosqlDatabases/AGSDataStore_bigdata_bds_wynb7v2u",
  "type": "nosql",
  "id": "6a6acb81-492c-416c-bfbf-feb3b8fa845f",
  "childItems": [],
  "provider": "ArcGIS Data Store",
  "info": {
    "clusterName": "bds_wynb7v2u",
    "dsFeature": "spatioTemporal",
    "isManaged": true,
    "systemManaged": true,
    "isManagedData": true,
    "factory": "nosql",
    "implementation": "Opensearch",
    "category": "database",
    "provider": "ArcGIS Data Store",
    "purposes": ["feature-spatiotemporal"],
    "datastoreName": "bds_wynb7v2u",
    "datastoreAlias": "agsbigdatastore-1",
    "httpScheme": "HTTPS_ONLY",
    "users": [
      {
        "username": "els_6xfrl8g",
        "password": "<encrypted_password>",
        "role": "admin"
      },
      {
        "username": "ags_943nl1r",
        "password": "<encrypted_password>",
        "role": "arcgis"
      }
    ],
    "nodeDnName": "<encrypted node domain name>",
    "rootCACert": "<encrypted rootCACert>",
    "adminKey": "<encrypted adminKey>",
    "adminPem": "<encrypted adminPem>",
    "nodeKey": "<encrypted nodeKey>",
    "nodePem": <encrypted nodePem info>",
    "machines": [{
      "role": "BIGDATA_ONLY",
      "name": "ORGANIZATION.EXAMPLE.COM",
      "httpPort": 9220,
      "transportPort": 9320,
      "dbPort": 9320,
      "adminURL": "https://ORGANIZATION.EXAMPLE.COM:2443/arcgis/datastoreadmin/",
      "platform": "Windows",
      "isCoordinatorNode": true,
      "isDataNode": true
    }],
    "clusterFinalized": true,
    "connectionString": "ENCRYPTED_PASSWORD_UTF8=00022e684b71337776765371664f6974472f2f4f6868475a324a326f6a4a394b77524169727566754a59734230346b3d2a00;ENCRYPTED_PASSWORD=00022e68363147664253725336586a417347386a586250456d3068334c4659464534456a50486748523234622f70593d2a00;SERVER=ORGANIZATION.EXAMPLE.COM;INSTANCE=opensearch:ORGANIZATION.EXAMPLE.COM:9220;DBCLIENT=opensearch;DB_CONNECTION_PROPERTIES=ORGANIZATION.EXAMPLE.COM:9220;DATABASE=bds_wynb7v2u;USER=ags_943nl1r;AUTHENTICATION_MODE=DBMS",
    "clusterUUID": "WnHClaBTSWOYfTsbj5HKLw"
  }
}

Cloud store examples

Amazon S3

The example below demonstrates a sample JSON object for an Amazon S3 cloud store that uses access key authentication:

Use dark colors for code blocksCopy
{
  "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\"}"
  }
}

The example below demonstrates a sample JSON object for an Amazon S3 cloud store that uses IAM role authentication:

Use dark colors for code blocksCopy
{
  "path": "/cloudStores/<value>",
  "type": "cloudStore",
  "provider": "amazon",
  "info": {
    "objectStore": "<bucketName>/<folderName>",
    "connectionString": "{\"credentialType\":\"IAMRole\",\"regionEndpointUrl\":\"<myPrivateRegionEndpointUrlinS3>\",\"defaultEndpointsProtocol\":\"https\",\"region\":\"af-south-1\"}"
  }
}

The example below demonstrates a sample JSON object for an Amazon S3 cloud store, that uses access key authentication, with access points for private cloud storage:

Use dark colors for code blocksCopy
{
  "path": "/cloudStores/<value>",
  "type": "cloudStore",
  "provider": "amazon",
  "info": {
    "objectStore": "<bucketName>/<folderName>",
    "connectionString": "{\"credentialType\":\"accesskey\",\"accessKeyId\":\"<value>\",\"secretAccessKey\":\"<value>\",\"regionEndpointUrl\":\"<myPrivateRegionEndpointUrlinS3>\",\"defaultEndpointsProtocol\": \"https\"}"
  }
}

Azure Blob

The example below demonstrates a sample JSON object for a public Microsoft Azure cloud store that uses shared key (accountKey) authentication:

Use dark colors for code blocksCopy
{
  "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 (accountKey) authentication:

Use dark colors for code blocksCopy
{
  "path": "/cloudStores/<value>",
  "type": "cloudStore",
  "provider": "azure",
  "info": {
    "objectStore": "<containerName>/<folderName>",
    "connectionString": "{\"credentialType\":\"accessKey\",\"accountKey\":\"<value>\",\"regionEndpointUrl\":\"<value>\",\"defaultEndpointsProtocol\":\"https\"}"
  }
}

The example below demonstrates a sample JSON object for a Microsoft Azure cloud store that uses service principal authentication:

Use dark colors for code blocksCopy
{
  "path": "/cloudStores/<value>",
  "type": "cloudStore",
  "provider": "azure",
  "info": {
    "objectStore": "<containerName>/<folderName>",
    "connectionString": "{\"credentialType\":\"servicePrincipal\",\"tenantId\":\"<value>\",\"clientId\":\"<value>\",\"clientSecret\":\"<value>\",\"authorityHost\":\"login.microsoftonline.com\",\"accountEndpoint\":\"core.windows.net\",\"accountName\":\"<value>\",\"defaultEndpointsProtocol\":\"https\"}"
  }
}

The example below demonstrates a sample JSON object for a Microsoft Azure cloud store that uses service principal authentication for anonymous access:

Use dark colors for code blocksCopy

{
  "path": "/cloudStores/Az_accountKey",
  "type": "cloudStore",
  "provider": "azure",
  "info": {
    "objectStore": "<containerName>/<folderName>",
    "connectionString": "{\"credentialType\":\"anonymous\",\"accountName\":\"overturemapswestus2\",\"accountEndpoint\":\"blob.core.windows.net\",\"defaultEndpointsProtocol\":\"https\"}"
  }
}

The example below demonstrates a sample JSON object for a Microsoft Azure cloud store that uses user-assigned managed identity authentication:

Use dark colors for code blocksCopy
{
  "path": "/cloudStores/<value>",
  "type": "cloudStore",
  "provider": "azure",
  "info": {
    "objectStore": "<containerName>/<folderName>",
    "connectionString": "{\"credentialType\":\"userAssignedIdentity\",\"managedIdentityClientId\":\"<value>\",\"accountName\":\"<value>\",\"accountEndpoint\":\"core.windows.net\",\"defaultEndpointsProtocol\":\"https\"}"
  }
}

The example below demonstrates a sample JSON object for a Microsoft Azure cloud store that uses shared access signature (sasToken) authentication:

Use dark colors for code blocksCopy
{
  "path": "/cloudStores/<value>",
  "type": "cloudStore",
  "provider": "azure",
  "info": {
    "objectStore": "<containerName>/<folderName>",
    "connectionString": "{\"credentialType\":\"sasToken\",\"sasToken\":\"<value>\",\"accountName\":\"<value>\",\"accountEndpoint\":\"core.windows.net\",\"defaultEndpointsProtocol\":\"https\"}"
  }
}

Google

The example below demonstrates a sample JSON object for a Google cloud store data item:

Use dark colors for code blocksCopy
{
  "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:

Use dark colors for code blocksCopy

{
  "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

ArcGIS Object Store

The example below demonstrates a sample JSON object for an ArcGIS Object Store installed to a machine reachable by the Video Server:

Use dark colors for code blocksCopy
{
  "path": "/cloudStores/AGSDataStore_objectstore_oz_sow3a31",
  "type": "objectStore",
  "id": "ac8aee42-0c2c-4744-8223-c5561669569c",
  "childItems": [],
  "provider": "ArcGIS Data Store",
  "info": {
    "dsFeature": "objectStore",
    "isManaged": true,
    "systemManaged": true,
    "isManagedData": true,
    "deployMode": "singleInstance",
    "factory": "objectStore",
    "implementation": "Ozone",
    "category": "storage",
    "provider": "ArcGIS Data Store",
    "purposes": [
      "feature-tile",
      "scene"
    ],
    "supportedStorageClasses": ["REDUCED_REDUNDANCY"],
    "objectStore": "0123456789abcdef",
    "finalized": true,
    "datastoreName": "oz_sow3a31",
    "connectionString": "<encrypted connection string>",
    "accessKey": "<encrypted accesskey>",
    "secretKey": "<encrypted secretKey>",
    "sslEnabled": true,
    "machines": [{
      "name": "ORGANIZATION.EXAMPLE.COM",
      "isSCMEnabled": true,
      "isOMEnabled": true,
      "scmID": "lebg0",
      "omID": "wdvzv",
      "isSCMPrimordialNode": true,
      "managerNumber": 1,
      "dbVersion": "2.0.0",
      "role": "PRIMARY",
      "endpoint": "ORGANIZATION.EXAMPLE.COM:29879",
      "isDataNodeEnabled": true,
      "isS3GEnabled": true,
      "dbPort": 29879,
      "adminURL": "https://ORGANIZATION.EXAMPLE.COM:2443/arcgis/datastoreadmin/",
      "platform": "Windows"
    }]
  }
}

The example below demonstrates a sample JSON object for a file share data item where the folder for the publisher and ArcGIS Video Server use the same shared path:

Use dark colors for code blocksCopy
{
  "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
  }
}

The example below demonstrates a sample JSON object for a file share data item where the folder for the publisher and ArcGIS Video Server use local paths:

Use dark colors for code blocksCopy
{
  "path": "/fileShares/folder_replicated", //a unique path on the server
  "type": "folder", //as this is a folder
  "clientPath": "C:\\data", //the path to the folder from the client
  "info": {
    "path": "c:\\data", //the path to the folder from the server
    "dataStoreConnectionType": "replicated", //indicates that client and server are seeing the same datasets
    "hostName": "GRID3" //name of the client host
  }
}

JSON Response example

Use dark colors for code blocksCopy
{"status": "success"}