GetInstance - Key Management Service - Alibaba Cloud Documentation Center

Queries information about a specified instance.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

yundun-hsm:GetInstance

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	No	The ID of the HSM instance.	hsm-cn-vj30bil****

Response elements

Element	Type	Description	Example
	object	PlainResult
RequestId	string	The ID of the request. Alibaba Cloud generates this unique ID for each request. Use this ID to troubleshoot and locate issues.	4C467B38-3910-447D-87BC-AC049166F216
Instance	object	The instance information.
InstanceId	string	The ID of the HSM instance.	hsm-cn-g4t3jwsc****
Remark	string	The remarks.	hsmOnline
RegionId	string	The region ID.	cn-hangzhou
ZoneId	string	The zone ID.	cn-hangzhou-b
Vendor	string	The vendor information.	jnta
DeviceType	string	The device type.	jnta.SJJ1528-G
PqcEnabled	integer		1
TpsEnabled	integer
TenantIsolationType	string	The hardware isolation type of the HSM. Valid values: "vsm" for virtual HSM and "hostedHsm" for hosted hardware HSM.	hostedHsm
OrderId	string	The order ID.	23576634952****
IsTrial	boolean	Indicates whether the instance is a trial instance. true: Yes false: No	false
VpcId	string	The ID of the VPC to which the instance belongs.	vpc-uf69i66j9kmoko52p****
VSwitchId	string	The ID of the vSwitch configured for the HSM instance.	vsw-bp1mvfs31ltt0wyhf****
Ip	string	The IP address of the HSM instance in the VPC.	10.192.XX.XX
Whitelist	string	The list of IP addresses in the whitelist.	18.68.XX.XX
CreateTime	integer	The time when the instance was created.	1699515963000
ExpireTime	integer	The time when the instance expires.	1699496389720
ClusterId	string	The ID of the cluster to which the instance belongs.	cluster-w3G9vOJI2****
ClusterName	string	The name of the cluster.	cluster_online
Master	boolean	Indicates whether the instance is the master HSM. true: The instance is the master HSM. false: The instance is a worker HSM.	true
Status	string	The status of the instance. PENDING: The instance is not enabled. ACTIVE: The instance is active. EXPIRED: The instance is expired. INVALID: The instance is invalid. FAILURE: The instance failed to be created. RESET: The instance is being reset. PAUSED: The instance is paused. MODIFYING: The instance is being modified.	EXPIRED
CertificationUrl	string

Examples

Success response

JSON format

{
  "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
  "Instance": {
    "InstanceId": "hsm-cn-g4t3jwsc****",
    "Remark": "hsmOnline",
    "RegionId": "cn-hangzhou",
    "ZoneId": "cn-hangzhou-b",
    "Vendor": "jnta",
    "DeviceType": "jnta.SJJ1528-G",
    "PqcEnabled": 1,
    "TpsEnabled": 0,
    "TenantIsolationType": "hostedHsm",
    "OrderId": "23576634952****",
    "IsTrial": false,
    "VpcId": "vpc-uf69i66j9kmoko52p****",
    "VSwitchId": "vsw-bp1mvfs31ltt0wyhf****",
    "Ip": "10.192.XX.XX",
    "Whitelist": "18.68.XX.XX",
    "CreateTime": 1699515963000,
    "ExpireTime": 1699496389720,
    "ClusterId": "cluster-w3G9vOJI2****",
    "ClusterName": "cluster_online",
    "Master": true,
    "Status": "EXPIRED",
    "CertificationUrl": ""
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	SwitchMaster.InstanceInvalid	Instance not in the cluster.
400	LeaveCluster.MasterLast	Master instance can not leave a cluster until all other instances are left.
400	Certificate.ChainInvalid	Certificate chain invalid. Please make sure issuer certificate is the trust anchor and cluster certificate is signed by issuer certificate.
400	Certificate.FormatInvalid	Certificate format invalid. Cluster/Issuer certificate must be in PEM format.
400	ConfigClusterSubnet.DuplicateZone	VSwitches should not contain duplicate zones.
400	InvalidApiParam.Error	api param is invalid
400	InvalidClusterName	Invalid parameter clusterName.
400	InvalidPageSize	Invalid parameter pageSize.
400	InvalidCurrentPage	Invalid parameter currentPage.
400	InvalidRegionId	Invalid parameter regionId.
400	InvalidVSwitch	Invalid parameter vSwitch.
400	InvalidVpc	Invalid parameter vpcId.
400	InvalidIp	Invalid parameter IP.
400	InvalidAliuid	Invalid parameter aliuid.
400	InvalidClusterId	Invalid parameter clusterId.
400	InvalidInstanceId	Invalid parameter instanceId.
400	InvalidBackupId	Invalid parameter backupId.
400	InvalidImageId	Invalid parameter imageId.
400	HsmInstanceNotExist.Error	hsm instance not exist
400	HSMIntanceNotActived.Error	hsm intance is not actived
400	WhiteListMaxCount.Error	whilte list is more than max count
400	ClusterIdIsNotExists.Error	cluster ID non-exists
400	InstanceListIsEmpty.Error	instance list is empty
400	InstanceIdIsEmpty.Error	instance id is empty
400	InstanceIsNotExistsInCluster.Error	cluster has no such instance
400	InstanceIsExistsInCluster.Error	instance already in the cluster
400	RegionNoEmpty.Error	region no. is empty
400	ClusterNameEmpty.Error	empty cluster name not allowed
400	ClusterNameIsExists.Error	the cluster name is already taken
400	IpNotValid.Error	ip not valid
400	ClusterIsEmpty.Error	cluster is empty
400	NoMasterFoundInCluster.Error	cluster has no master instance
400	HsmInstanceIdNotFound.Error	no such instance
400	NoInstanceFoundInCluster.Error	cluster is empty
400	Whitelist.Invalid	Whitelist blocks not in CIDR format.
400	Whitelist.TooLong	Whitelist too long, exceeds 10 CIDR blocks.
500	ConfigWhitelistFailed.Error	config white list error
500	ActionFailed.Error	internal error, please try again
500	InternalError	The request processing has failed due to some unknown error.	Unknown error caused request processing to fail.
403	Forbidden.InstanceInCluster	This API is forbidden for instances in cluster.
403	JoinCluster.InstanceIncorrectState	Instance not in Active/Pending state.
403	NoPermission	Caller has no permission on the resource.
403	InstanceNotPaused	Please pause the instance before reset.
403	InstanceNotActive	Instance is not active.
403	ConfigIp.IncorrectState	Instance not in pending or active state, can not config IP address.
403	SwitchMaster.IncorrectState	Cluster not initialized, please initialize the cluster first.
403	SyncCluster.IncorrectState	Cluster not initialized, please initialize the cluster first.
403	LeaveCluster.InstanceInvalid	The instance is not in the cluster.
403	DeleteCluster.IncorrectState	Cluster not empty, please remove all instances first.
403	JoinCluster.InstanceVSwitchNotInCluster	Instance's vSwitch is not in cluster config, please change instance's vSwitch first.
403	JoinCluster.InstanceInitialized	Initialized instance can not join a cluster.
403	JoinCluster.IncorrectState	Cluster not initialized, please initialize the cluster first.
403	InitializeCluster.InstanceNotInitialized	Cluster master instance not initialized, please initialize cluster master instance first.
403	InitializeCluster.IncorrectConfig	Cluster subnet not configured, please config cluster subnet first.
403	InitializeCluster.IncorrectState	Cluster initialized, do not re-initialize.
403	Cluster.CN.ActionForbidden	This API is forbidden for non-international site cluster.
403	Cluster.INTL.ActionForbidden	This API is forbidden for international site cluster.
403	ConfigClusterCertificate.IncorrectState	Cluster initialized or certificates already configured.
403	ConfigClusterSubnet.InvalidVpcId	VPC Id invalid. Cluster VPC is the same as cluster master's VPC.
403	ConfigClusterSubnet.InvalidVSwitchId	VSwitch Id invalid. VSwitches should contain all current cluster vSwitches.
403	ConfigClusterSubnet.IncorrectState	Cluster not in NEW state, can not config cluster subnet.
403	ClusterName.Exist	Cluster name already exists, please use another name.
404	Resource.NotFound	Resource not found.
405	ClusterAPI.NotSupported	ClusterAPI not supported in this region.
409	Conflict.InstanceModifying	Instance is being modified by a previous request. Please try again later.
409	Conflict	Resource is being updated by a previous request. Current request is redundant.
409	Cluster.Conflict	The cluster is being updated by a previous request. Please try again later.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.