Register (Backup Store) | ArcGIS REST APIs

URL:: https://<root>/system/disasterrecovery/stores/register
Methods:: POST
Version Introduced:: 10.9

Access requirements

Required privileges

The Enterprise 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.

Security and infrastructure

Tokens

This API requires token-based authentication. A token is automatically generated for administrators who sign in to the Enterprise 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 generateToken operation in the Enterprise Directory API. For security reasons, all POST requests made to the Enterprise Administrator API must include a token in the request body.

Learn how to generate a token

Description

The register operation registers a backup store. The backup store is created and managed by the deployment.

Request parameters

Parameter	Details
`storeName` (Required)	The backup store name.
`settings` (Required)	The JSON describing the storage configuration for the backup store. It can use either file-based storage or cloud storage. Support for cloud storage was added at ArcGIS Enterprise on Kubernetes 11.2. Support for enabling spatiotemporal data backups using the `supportBDSBackup` property was added at 12.0. For more information, see the Settings properties section below.
`isDefault` (Required)	Specifies whether the store will be the default backup store (`true`). The default value is `false`. Values: `true` \| `false`
`async`	Introduced at 11.0. This parameter specifies whether the operation will run synchronously or asynchronously. If `false`, the operation is run synchronously. If `true`, the operation is run asynchronously and the response returns a JSON object containing job information that can be used to track the job's status. The default value is `false`. Values: `true` \| `false`
`f`	The response format. The default format is `html`. Values: `html` \| `json` \| `pjson`

Settings properties

The following information pertains to the different storage options (file-based storage or cloud storage) and settings available for a backup store.

File-based storage

If the backup store uses file-based storage, the storage configuration will use persistent volumes that can either be statically provisioned and bound by label selectors or dynamically provisioned. The following table outlines the properties for file-based storage configuration:

Property	Details
`provisioningType`	The provisioning type. Values: `STATIC` \| `DYNAMIC`
`storageClass`	The storage class.
`size`	The size for the persistent volume. The minimum size requirement is 16 GB.
`labels`	A `key:value` pair to identify and bind to a persistent volume.

STATIC JSON examples

The following example demonstrates the storageConfig syntax when using a STATIC provisioning type:

Use dark colors for code blocksCopy
{
  "provisioningType": "STATIC",
  "storageClass": "backups",
  "size": "64Gi",
  "labels": {
    "arcgis/purpose": "backups"
  }
}

The following example demonstrates the full JSON for the settings parameter using STATIC provisioning and label selectors:

Use dark colors for code blocksCopy
{
  "type": "HOSTED",
  "storageConfig": {
    "provisioningType": "STATIC",
    "storageClass": "backups",
    "size": "64Gi",
    "labels": {
      "arcgis/purpose": "backups"
    }
  }
}

DYNAMIC JSON examples

The following example demonstrates the storageConfig syntax when using a DYNAMIC provisioning type:

Use dark colors for code blocksCopy
{
  "size": "64Gi",
  "provisioningType": "DYNAMIC",
  "storageClass": "backups"
}

The following example demonstrates the full JSON for the settings parameter using DYNAMIC provisioning:

Use dark colors for code blocksCopy
{
  "type": "HOSTED",
  "storageConfig": {
    "size": "64Gi",
    "provisioningType": "DYNAMIC",
    "storageClass": "backups"
  }
}

Cloud storage

If the backup store uses native cloud storage, the JSON for the settings parameter must include relevant properties for the storage provider. Supported cloud storage locations are Amazon Simple Storage Service (S3), Azure Blob Storage, and Google Cloud Storage (GCS).

The JSON for cloud storage configuration contains two main sections:

provider: Defines how to connect and the credentials to use.
service: Includes the bucket or container to use, as well as region information (if relevant).

Warning
If an empty string is provided for rootDir when a backup store is registered, the backup store's rootFolderName will, by default, become arcgis. However, if a root directory named arcgis already exists, administrators must specify a unique value for rootDir.

Starting at ArcGIS Enterprise 11.2 on Kubernetes, administrators can choose to register a backup store using provider-level credentials or using service-level credentials. Choosing to use service-level credentials allows for the cloud-native object store to be configured using one set of access keys and use a separate set of access keys for the backup store. Administrators choosing to use the provider-level credentials need to ensure that they are using the current credentials assigned to the cloud store.

Amazon S3 (provider-level credentials)

The following example shows the JSON properties needed for the settings parameter for Amazon S3 cloud storage using provider-level credentials:

Use dark colors for code blocksCopy
{
  "type": "S3",
  "provider": {
    "name": "AWS",
    "id": "<providerId>",
    "cloudServices": [
      {
        "name": "AWS S3",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "bucketName": "<bucketName>",
          "region": "<region>",
          "rootDir": "<rootDirectory>"
        },
        "category": "storage"
      }
    ]
  }
}

Amazon S3 (service-level credentials)

The following example shows the JSON properties needed for the settings parameter for Amazon S3 cloud storage using service-level credentials:

Use dark colors for code blocksCopy
{
  "type": "S3",
  "provider": {
    "name": "AWS",
    "cloudServices": [
      {
        "name": "AWS S3",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "bucketName": "<bucket>",
          "region": "<region>",
          "rootDir": "<rootDirectory>",
          "credential": {
            "type": "ACCESS-KEY",
            "secret": {
              "secretKey": "<secretAccessKey>",
              "accessKey": "<accessKey>"
            }
          }
        },
        "category": "storage"
      }
    ]
  }
}

The JSON example below shows the properties needed for the settings parameter for Amazon S3 cloud storage configured with AWS Identity and Access Management (IAM) roles, also using service-level credentials:

Use dark colors for code blocksCopy
{
  "type": "S3",
  "provider": {
    "name": "AWS",
    "cloudServices": [
      {
        "name": "AWS S3",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "bucketName": "<bucket>",
          "region": "<region>",
          "rootDir": "<rootDirectory>",
          "credential": {
            "type": "IAM-ROLE"
          }
        },
        "category": "storage"
      }
    ]
  }
}

Azure Blob Storage (provider-level credentials)

The following example shows the JSON properties needed for the settings parameter for Azure Blob Storage using provider-level credentials:

Use dark colors for code blocksCopy
{
  "type": "AZURE_BLOBSTORE",
  "provider": {
    "name": "AZURE",
    "id": "<providerId>",
    "cloudServices": [
      {
        "name": "Azure Blob Store",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "containerName": "<containerName>",
          "rootDir": "<rootDirectory>"
        },
        "category": "storage"
      }
    ]
  }
}

Azure Blob Storage (service-level credentials)

The following example shows the JSON properties needed for the settings parameter for Azure Blob Storage with storage account keys using service-level credentials:

Use dark colors for code blocksCopy
{
  "type": "AZURE_BLOBSTORE",
  "provider": {
    "name": "AZURE",
    "cloudServices": [
      {
        "name": "Azure Blob Store",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "containerName": "<containerName>",
          "rootDir": "<rootDirectory>",
          "credential": {
            "type": "STORAGE-ACCOUNT-KEY",
            "secret": {
              "storageAccountName": "<storageAccountName>",
              "storageAccountKey": "<storageAccountKey>"
            }
          }
        },
        "category": "storage"
      }
    ]
  }
}

The JSON example below shows the properties needed for the settings parameter for Azure Blob Storage with system-assigned identities, also using service-level credentials:

Use dark colors for code blocksCopy
{
  "type": "AZURE_BLOBSTORE",
  "provider": {
    "name": "AZURE",
    "cloudServices": [
      {
        "name": "Azure Blob Store",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "containerName": "<containerName>",
          "rootDir": "<rootDirectory>",
          "credential": {
            "type": "SYSTEM-ASSIGNED-IDENTITY",
            "secret": {
              "storageAccountName": "<storageAccountName>"
            }
          }
        },
        "category": "storage"
      }
    ]
  }
}

The JSON example below shows the properties needed for the settings parameter for Azure Blob Storage with user-assigned identities, also using service-level credentials:

Use dark colors for code blocksCopy
{
  "type": "AZURE_BLOBSTORE",
  "provider": {
    "name": "AZURE",
    "cloudServices": [
      {
        "name": "Azure Blob Store",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "containerName": "<containerName>",
          "rootDir": "<rootDirectory>",
          "credential": {
            "type": "USER-ASSIGNED-IDENTITY",
            "managedIdentityClientId": "<user_assigned_identity_client_id>",
            "secret": {
              "storageAccountName": "<storageAccountName>"
            }
          }
        },
        "category": "storage"
      }
    ]
  }
}

Google Cloud Storage (provider-level credentials)

The following example shows the JSON properties needed for the settings parameter for Google Cloud Storage using provider-level credentials:

Use dark colors for code blocksCopy
{
  "type": "GCS",
  "provider": {
    "name": "GCP",
    "id": "<providerId>",
    "cloudServices": [
      {
        "name": "Google Cloud Storage",
        "connection": {
          "bucketName": "<bucketName>",
          "rootDir": "<rootDirectory>"
        },
        "usage": "BACKUP",
        "type": "objectStore",
        "category": "storage"
      }
    ]
  }
}

Google Cloud Storage (service-level credentials)

The following example shows the JSON properties needed for the settings parameter for Google Cloud Storage with HMAC keys using service-level credentials:

Use dark colors for code blocksCopy
{
  "type": "GCS",
  "provider": {
    "name": "GCP",
    "cloudServices": [
      {
        "name": "Google Cloud Storage",
        "type": "objectStore",
        "usage": "BACKUP",
        "connection": {
          "bucketName": "<bucket>",
          "rootDir": "<rootDirectory>",
          "credential": {
            "type": "HMAC-KEYS",
            "secret": {
              "secretKey": "<secretAccessKey>",
              "accessKey": "<accessKey>"
            }
          }
        },
        "category": "storage"
      }
    ]
  }
}

Spatiotemporal backups

Starting at 12.0, you can register a backup store to support spatiotemporal data, such as data created from location tracking. The boolean supportBDSBackup property determines whether to prepare the backup store to support spatiotemporal data backups. The supportBDSBackup property is false by default.

The following example demonstrates the full JSON for the settings parameter when registering a backup store using file-based storage and including spatiotemporal backups:

Use dark colors for code blocksCopy
{
  "supportBDSBackup": true,
  "type": "HOSTED",
  "storageConfig": {
    "provisioningType": "STATIC",
    "storageClass": "backups",
    "size": "64Gi",
    "labels": {
      "arcgis/purpose": "backups"
    }
  }
}

Example usage

The following is a sample POST request for the register operation that demonstrates registering a backup store that uses dynamically provisioned file-based storage:

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

storeName=backupDefault&settings={"type": "HOSTED","storageConfig": {"size": "64Gi","provisioningType": "DYNAMIC","storageClass": "backups"}}&isDefault=true&async=false&f=pjson&token=Mb0ORrkLObNO2Q8FZoUCHHzSMzZi0CbhLHNRYMqqa6URG_ojQJF3rNsJAfRB23MyCrLwSmuaHPUo4AEIrUuoH1-4Ot5xh4565FtlQahXAhK2C7Sy0oydZhBwD8KdFSnVlnLr-

JSON Response example

If async is false, the following response is returned when a backup store has been registered successfully:

Use dark colors for code blocksCopy
{
  "default": true,
  "storageConfig": {"storageClassName": "backups"},
  "identity": "uh1rxq3x6x2zk1cxwtli",
  "name": "backups2",
  "identityKey": "zNUgyzzhuA6L6rSuD1RQUth/PWeg87/RVaGjDFpv2Ic=",
  "rootDir": "rootdir",
  "type": "HOSTED",
  "autoShutdown": true,
  "status": "success"
}

If async is true, the response returns a JSON object containing job information. The value returned for the jobsUrl property can be used to access the job resource, which can be polled to return updated job status information. For more information, see the Job resource topic.

Use dark colors for code blocksCopy
{
  "jobsUrl": "https://organization.example.com/<context>/admin/jobs/j7c8820d0-ea2f-427a-ab6f-a8cc2c927fe4",
  "jobid": "j7c8820d0-ea2f-427a-ab6f-a8cc2c927fe4",
  "status": "SUBMITTED"
}