Caches - Get

Service:

Storagecache

API Version:

2024-07-01

Returns a cache.

GET https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.StorageCache/caches/{cacheName}?api-version=2024-07-01

URI Parameters

Name	In	Required	Type	Description
cacheName	path	True	string pattern: ^[-0-9a-zA-Z_]{1,80}$	Name of cache. Length of name must not be greater than 80 and chars must be from the [-0-9a-zA-Z_] char class.
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string minLength: 1	The ID of the target subscription.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Responses

Name	Type	Description
200 OK	Cache	Returns the cache object corresponding to cache name.
Other Status Codes	CloudError	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Caches_Get

Sample request

HTTP

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/scgroup/providers/Microsoft.StorageCache/caches/sc1?api-version=2024-07-01

Sample response

Status code:

200

{
  "tags": {
    "Dept": "Contoso"
  },
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/scgroup/providers/Microsoft.StorageCache/caches/sc1",
  "location": "westus",
  "name": "sc1",
  "type": "Microsoft.StorageCache/Cache",
  "systemData": {
    "createdBy": "user1",
    "createdByType": "User",
    "createdAt": "2020-01-01T17:18:19.1234567Z",
    "lastModifiedBy": "user2",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-01-02T17:18:19.1234567Z"
  },
  "properties": {
    "cacheSizeGB": 3072,
    "health": {
      "state": "Transitioning",
      "statusDescription": "Cache is being created.",
      "conditions": [
        {
          "timestamp": "2021-04-21T18:25:43.511Z",
          "message": "Cannot contact DNS server"
        }
      ]
    },
    "mountAddresses": [
      "192.168.1.1",
      "192.168.1.2"
    ],
    "provisioningState": "Succeeded",
    "subnet": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/scgroup/providers/Microsoft.Network/virtualNetworks/scvnet/subnets/sub1",
    "upgradeStatus": {
      "currentFirmwareVersion": "2022.08.1",
      "firmwareUpdateStatus": "available",
      "firmwareUpdateDeadline": "2019-04-21T18:25:43.511Z",
      "lastFirmwareUpdate": "2019-01-21T18:25:43.511Z",
      "pendingFirmwareVersion": "2022.08.1"
    },
    "networkSettings": {
      "mtu": 1500,
      "dnsServers": [
        "10.1.22.33",
        "10.1.12.33"
      ],
      "dnsSearchDomain": "contoso.com",
      "ntpServer": "time.contoso.com"
    },
    "securitySettings": {
      "accessPolicies": [
        {
          "name": "default",
          "accessRules": [
            {
              "scope": "default",
              "access": "rw",
              "suid": false,
              "submountAccess": true,
              "rootSquash": false
            }
          ]
        }
      ]
    },
    "upgradeSettings": {
      "upgradeScheduleEnabled": true,
      "scheduledTime": "2022-04-26T18:25:43.511Z"
    },
    "encryptionSettings": {
      "keyEncryptionKey": {
        "keyUrl": "https://keyvault-cmk.vault.azure.net/keys/key2048/test",
        "sourceVault": {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/scgroup/providers/Microsoft.KeyVault/vaults/keyvault-cmk"
        }
      }
    },
    "directoryServicesSettings": {
      "activeDirectory": {
        "primaryDnsIpAddress": "192.0.2.10",
        "secondaryDnsIpAddress": "192.0.2.11",
        "domainName": "contosoAd.contoso.local",
        "domainNetBiosName": "contosoAd",
        "cacheNetBiosName": "contosoSmb",
        "domainJoined": "Yes"
      },
      "usernameDownload": {
        "extendedGroups": true,
        "usernameSource": "LDAP",
        "groupFileURI": "http://contoso.net/group.file",
        "userFileURI": "http://contoso.net/passwd.file",
        "ldapServer": "192.0.2.12",
        "ldapBaseDN": "dc=contosoad,dc=contoso,dc=local",
        "encryptLdapConnection": false,
        "requireValidCertificate": false,
        "autoDownloadCertificate": false,
        "caCertificateURI": "http://contoso.net/cacert.pem",
        "usernameDownloaded": "Yes"
      }
    },
    "primingJobs": [
      {
        "primingJobName": "contosoJob1",
        "primingJobId": "00000000000_0000000000",
        "primingJobState": "Complete",
        "primingJobStatus": "success",
        "primingJobDetails": "Files: Cached=635, Failed=0, Excluded=80, Data=346030 bytes, Directories: Cached=1003, Failed=0, Excluded=0",
        "primingJobPercentComplete": 100
      },
      {
        "primingJobName": "contosoJob2",
        "primingJobId": "11111111111_1111111111",
        "primingJobState": "Queued",
        "primingJobStatus": "",
        "primingJobDetails": "",
        "primingJobPercentComplete": 0
      }
    ],
    "spaceAllocation": [
      {
        "name": "st1",
        "allocationPercentage": 25
      },
      {
        "name": "st2",
        "allocationPercentage": 50
      },
      {
        "name": "st3",
        "allocationPercentage": 25
      }
    ],
    "zones": [
      "1"
    ]
  },
  "sku": {
    "name": "Standard_2G"
  }
}

Definitions

Name	Description
Cache	A cache instance. Follows Azure Resource Manager standards: https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/resource-api-reference.md
CacheActiveDirectorySettings	Active Directory settings used to join a cache to a domain.
CacheDirectorySettings	Cache Directory Services settings.
CacheEncryptionSettings	Cache encryption settings.
CacheHealth	An indication of cache health. Gives more information about health than just that related to provisioning.
CacheIdentity	Cache identity properties.
CacheIdentityType	The type of identity used for the cache
CacheNetworkSettings	Cache network settings.
CacheSecuritySettings	Cache security settings.
CacheUpgradeSettings	Cache Upgrade Settings.
CacheUpgradeStatus	Properties describing the software upgrade state of the cache.
CacheUsernameDownloadSettings	Settings for Extended Groups username and group download.
CloudError	An error response.
CloudErrorBody	An error response.
Condition	Outstanding conditions that will need to be resolved.
createdByType	The type of identity that created the resource.
Credentials	Active Directory admin credentials used to join the HPC Cache to a domain.
DomainJoinedType	True if the HPC Cache is joined to the Active Directory domain.
FirmwareStatusType	True if there is a firmware update ready to install on this cache. The firmware will automatically be installed after firmwareUpdateDeadline if not triggered earlier via the upgrade operation.
HealthStateType	List of cache health states. Down is when the cluster is not responding. Degraded is when its functioning but has some alerts. Transitioning when it is creating or deleting. Unknown will be returned in old api versions when a new value is added in future versions. WaitingForKey is when the create is waiting for the system assigned identity to be given access to the encryption key in the encryption settings.
KeyVaultKeyReference	Describes a reference to key vault key.
NfsAccessPolicy	A set of rules describing access policies applied to NFSv3 clients of the cache.
NfsAccessRule	Rule to place restrictions on portions of the cache namespace being presented to clients.
NfsAccessRuleAccess	Access allowed by this rule.
NfsAccessRuleScope	Scope for this rule. The scope and filter determine which clients match the rule.
PrimingJob	A priming job instance.
PrimingJobState	The state of the priming operation.
ProvisioningStateType	ARM provisioning state, see https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/Addendum.md#provisioningstate-property
Sku	SKU for the cache.
SourceVault	Describes a resource Id to source key vault.
StorageTargetSpaceAllocation	Storage Target space allocation properties.
systemData	Metadata pertaining to creation and last modification of the resource.
UserAssignedIdentities	A dictionary where each key is a user assigned identity resource ID, and each key's value is an empty dictionary.
UsernameDownloadedType	Indicates whether or not the HPC Cache has performed the username download successfully.
UsernameSource	This setting determines how the cache gets username and group names for clients.

Cache

Object

A cache instance. Follows Azure Resource Manager standards: https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/resource-api-reference.md

Name	Type	Description
id	string	Resource ID of the cache.
identity	CacheIdentity	The identity of the cache, if configured.
location	string	Region name string.
name	string pattern: ^[-0-9a-zA-Z_]{1,80}$	Name of cache.
properties.cacheSizeGB	integer (int32)	The size of this Cache, in GB.
properties.directoryServicesSettings	CacheDirectorySettings	Specifies Directory Services settings of the cache.
properties.encryptionSettings	CacheEncryptionSettings	Specifies encryption settings of the cache.
properties.health	CacheHealth	Health of the cache.
properties.mountAddresses	string[]	Array of IPv4 addresses that can be used by clients mounting this cache.
properties.networkSettings	CacheNetworkSettings	Specifies network settings of the cache.
properties.primingJobs	PrimingJob[]	Specifies the priming jobs defined in the cache.
properties.provisioningState	ProvisioningStateType	ARM provisioning state, see https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/Addendum.md#provisioningstate-property
properties.securitySettings	CacheSecuritySettings	Specifies security settings of the cache.
properties.spaceAllocation	StorageTargetSpaceAllocation[]	Specifies the space allocation percentage for each storage target in the cache.
properties.subnet	string	Subnet used for the cache.
properties.upgradeSettings	CacheUpgradeSettings	Upgrade settings of the cache.
properties.upgradeStatus	CacheUpgradeStatus	Upgrade status of the cache.
properties.zones	string[]	Availability zones for resources. This field should only contain a single element in the array.
sku	Sku	SKU for the cache.
systemData	systemData	The system meta data relating to this resource.
tags	object	Resource tags.
type	string	Type of the cache; Microsoft.StorageCache/Cache

CacheActiveDirectorySettings

Object

Active Directory settings used to join a cache to a domain.

Name	Type	Description
cacheNetBiosName	string pattern: ^[-0-9a-zA-Z]{1,15}$	The NetBIOS name to assign to the HPC Cache when it joins the Active Directory domain as a server. Length must 1-15 characters from the class [-0-9a-zA-Z].
credentials	Credentials	Active Directory admin credentials used to join the HPC Cache to a domain.
domainJoined	DomainJoinedType	True if the HPC Cache is joined to the Active Directory domain.
domainName	string	The fully qualified domain name of the Active Directory domain controller.
domainNetBiosName	string	The Active Directory domain's NetBIOS name.
primaryDnsIpAddress	string	Primary DNS IP address used to resolve the Active Directory domain controller's fully qualified domain name.
secondaryDnsIpAddress	string	Secondary DNS IP address used to resolve the Active Directory domain controller's fully qualified domain name.

CacheDirectorySettings

Object

Cache Directory Services settings.

Name	Type	Description
activeDirectory	CacheActiveDirectorySettings	Specifies settings for joining the HPC Cache to an Active Directory domain.
usernameDownload	CacheUsernameDownloadSettings	Specifies settings for Extended Groups. Extended Groups allows users to be members of more than 16 groups.

CacheEncryptionSettings

Object

Cache encryption settings.

Name	Type	Description
keyEncryptionKey	KeyVaultKeyReference	Specifies the location of the key encryption key in key vault.
rotationToLatestKeyVersionEnabled	boolean	Specifies whether the service will automatically rotate to the newest version of the key in the key vault.

CacheHealth

Object

An indication of cache health. Gives more information about health than just that related to provisioning.

Name	Type	Description
conditions	Condition[]	Outstanding conditions that need to be investigated and resolved.
state	HealthStateType	List of cache health states. Down is when the cluster is not responding. Degraded is when its functioning but has some alerts. Transitioning when it is creating or deleting. Unknown will be returned in old api versions when a new value is added in future versions. WaitingForKey is when the create is waiting for the system assigned identity to be given access to the encryption key in the encryption settings.
statusDescription	string	Describes explanation of state.

CacheIdentity

Object

Cache identity properties.

Name	Type	Description
principalId	string	The principal ID for the system-assigned identity of the cache.
tenantId	string	The tenant ID associated with the cache.
type	CacheIdentityType	The type of identity used for the cache
userAssignedIdentities	UserAssignedIdentities	A dictionary where each key is a user assigned identity resource ID, and each key's value is an empty dictionary.

CacheIdentityType

Enumeration

The type of identity used for the cache

Value	Description
None
SystemAssigned
SystemAssigned, UserAssigned
UserAssigned

CacheNetworkSettings

Object

Cache network settings.

Name	Type	Default value	Description
dnsSearchDomain	string		DNS search domain
dnsServers	string[]		DNS servers for the cache to use. It will be set from the network configuration if no value is provided.
mtu	integer (int32) minimum: 576 maximum: 1500	1500	The IPv4 maximum transmission unit configured for the subnet.
ntpServer	string	time.windows.com	NTP server IP Address or FQDN for the cache to use. The default is time.windows.com.
utilityAddresses	string[]		Array of additional IP addresses used by this cache.

CacheSecuritySettings

Object

Cache security settings.

Name	Type	Description
accessPolicies	NfsAccessPolicy[]	NFS access policies defined for this cache.

CacheUpgradeSettings

Object

Cache Upgrade Settings.

Name	Type	Description
scheduledTime	string (date-time)	When upgradeScheduleEnabled is true, this field holds the user-chosen upgrade time. At the user-chosen time, the firmware update will automatically be installed on the cache.
upgradeScheduleEnabled	boolean	True if the user chooses to select an installation time between now and firmwareUpdateDeadline. Else the firmware will automatically be installed after firmwareUpdateDeadline if not triggered earlier via the upgrade operation.

CacheUpgradeStatus

Object

Properties describing the software upgrade state of the cache.

Name	Type	Description
currentFirmwareVersion	string	Version string of the firmware currently installed on this cache.
firmwareUpdateDeadline	string (date-time)	Time at which the pending firmware update will automatically be installed on the cache.
firmwareUpdateStatus	FirmwareStatusType	True if there is a firmware update ready to install on this cache. The firmware will automatically be installed after firmwareUpdateDeadline if not triggered earlier via the upgrade operation.
lastFirmwareUpdate	string (date-time)	Time of the last successful firmware update.
pendingFirmwareVersion	string	When firmwareUpdateAvailable is true, this field holds the version string for the update.

CacheUsernameDownloadSettings

Object

Settings for Extended Groups username and group download.

Name	Type	Default value	Description
autoDownloadCertificate	boolean	False	Determines if the certificate should be automatically downloaded. This applies to 'caCertificateURI' only if 'requireValidCertificate' is true.
caCertificateURI	string		The URI of the CA certificate to validate the LDAP secure connection. This field must be populated when 'requireValidCertificate' is set to true.
credentials	Credentials		When present, these are the credentials for the secure LDAP connection.
encryptLdapConnection	boolean	False	Whether or not the LDAP connection should be encrypted.
extendedGroups	boolean		Whether or not Extended Groups is enabled.
groupFileURI	string		The URI of the file containing group information (in /etc/group file format). This field must be populated when 'usernameSource' is set to 'File'.
ldapBaseDN	string		The base distinguished name for the LDAP domain.
ldapServer	string		The fully qualified domain name or IP address of the LDAP server to use.
requireValidCertificate	boolean	False	Determines if the certificates must be validated by a certificate authority. When true, caCertificateURI must be provided.
userFileURI	string		The URI of the file containing user information (in /etc/passwd file format). This field must be populated when 'usernameSource' is set to 'File'.
usernameDownloaded	UsernameDownloadedType		Indicates whether or not the HPC Cache has performed the username download successfully.
usernameSource	UsernameSource	None	This setting determines how the cache gets username and group names for clients.

CloudError

Object

An error response.

Name	Type	Description
error	CloudErrorBody	The body of the error.

CloudErrorBody

Object

An error response.

Name	Type	Description
code	string	An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
details	CloudErrorBody[]	A list of additional details about the error.
message	string	A message describing the error, intended to be suitable for display in a user interface.
target	string	The target of the particular error. For example, the name of the property in error.

Condition

Object

Outstanding conditions that will need to be resolved.

Name	Type	Description
message	string	The issue requiring attention.
timestamp	string (date-time)	The time when the condition was raised.

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
Application
Key
ManagedIdentity
User

Credentials

Object

Active Directory admin credentials used to join the HPC Cache to a domain.

Name	Type	Description
password	string	Plain text password of the Active Directory domain administrator. This value is stored encrypted and not returned on response.
username	string	Username of the Active Directory domain administrator. This value is stored encrypted and not returned on response.

DomainJoinedType

Enumeration

True if the HPC Cache is joined to the Active Directory domain.

Value	Description
Error
No
Yes

FirmwareStatusType

Enumeration

True if there is a firmware update ready to install on this cache. The firmware will automatically be installed after firmwareUpdateDeadline if not triggered earlier via the upgrade operation.

Value	Description
available
unavailable

HealthStateType

Enumeration

List of cache health states. Down is when the cluster is not responding. Degraded is when its functioning but has some alerts. Transitioning when it is creating or deleting. Unknown will be returned in old api versions when a new value is added in future versions. WaitingForKey is when the create is waiting for the system assigned identity to be given access to the encryption key in the encryption settings.

Value	Description
Degraded
Down
Flushing
Healthy
StartFailed
Stopped
Stopping
Transitioning
Unknown
UpgradeFailed
Upgrading
WaitingForKey

KeyVaultKeyReference

Object

Describes a reference to key vault key.

Name	Type	Description
keyUrl	string	The URL referencing a key encryption key in key vault.
sourceVault	SourceVault	Describes a resource Id to source key vault.

NfsAccessPolicy

Object

A set of rules describing access policies applied to NFSv3 clients of the cache.

Name	Type	Description
accessRules	NfsAccessRule[]	The set of rules describing client accesses allowed under this policy.
name	string	Name identifying this policy. Access Policy names are not case sensitive.

NfsAccessRule

Object

Rule to place restrictions on portions of the cache namespace being presented to clients.

Name	Type	Description
access	NfsAccessRuleAccess	Access allowed by this rule.
anonymousGID	string	GID value that replaces 0 when rootSquash is true. This will use the value of anonymousUID if not provided.
anonymousUID	string	UID value that replaces 0 when rootSquash is true. 65534 will be used if not provided.
filter	string	Filter applied to the scope for this rule. The filter's format depends on its scope. 'default' scope matches all clients and has no filter value. 'network' scope takes a filter in CIDR format (for example, 10.99.1.0/24). 'host' takes an IP address or fully qualified domain name as filter. If a client does not match any filter rule and there is no default rule, access is denied.
rootSquash	boolean	Map root accesses to anonymousUID and anonymousGID.
scope	NfsAccessRuleScope	Scope for this rule. The scope and filter determine which clients match the rule.
submountAccess	boolean	For the default policy, allow access to subdirectories under the root export. If this is set to no, clients can only mount the path '/'. If set to yes, clients can mount a deeper path, like '/a/b'.
suid	boolean	Allow SUID semantics.

NfsAccessRuleAccess

Enumeration

Access allowed by this rule.

Value	Description
no
ro
rw

NfsAccessRuleScope

Enumeration

Scope for this rule. The scope and filter determine which clients match the rule.

Value	Description
default
host
network

PrimingJob

Object

A priming job instance.

Name	Type	Description
primingJobDetails	string	The job details or error information if any.
primingJobId	string pattern: ^[-0-9a-zA-Z_]{1,80}$	The unique identifier of the priming job.
primingJobName	string pattern: ^[-0-9a-zA-Z_]{1,80}$	The priming job name.
primingJobPercentComplete	number (double) minimum: 0 maximum: 100	The current progress of the priming job, as a percentage.
primingJobState	PrimingJobState	The state of the priming operation.
primingJobStatus	string	The status code of the priming job.
primingManifestUrl	string	The URL for the priming manifest file to download. This file must be readable from the HPC Cache. When the file is in Azure blob storage the URL should include a Shared Access Signature (SAS) granting read permissions on the blob.

PrimingJobState

Enumeration

The state of the priming operation.

Value	Description
Complete
Paused
Queued
Running

ProvisioningStateType

Enumeration

ARM provisioning state, see https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/Addendum.md#provisioningstate-property

Value	Description
Canceled
Creating
Deleting
Failed
Succeeded
Updating

Sku

Object

SKU for the cache.

Name	Type	Description
name	string	SKU name for this cache.

SourceVault

Object

Describes a resource Id to source key vault.

Name	Type	Description
id	string	Resource Id.

StorageTargetSpaceAllocation

Object

Storage Target space allocation properties.

Name	Type	Description
allocationPercentage	integer (int32) minimum: 1 maximum: 100	The percentage of cache space allocated for this storage target
name	string pattern: ^[-0-9a-zA-Z_]{1,80}$	Name of the storage target.

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string (date-time)	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string (date-time)	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

UserAssignedIdentities

Object

A dictionary where each key is a user assigned identity resource ID, and each key's value is an empty dictionary.

Name	Type	Description

UsernameDownloadedType

Enumeration

Indicates whether or not the HPC Cache has performed the username download successfully.

Value	Description
Error
No
Yes

UsernameSource

Enumeration

This setting determines how the cache gets username and group names for clients.

Value	Description
AD
File
LDAP
None