Registering an Agent

Function

This API is used to register an agent during agent installation. This API is called automatically by the Agent. Manual registration is not required.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

POST /v3/{project_id}/agents

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. You can obtain it by calling the IAM API.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
agent	Yes	AgentRegister object	Agent registration parameters

**Table 4** AgentRegister
Parameter	Mandatory	Type	Description
agent_id	Yes	String	Agent ID
host_name	Yes	String	Name of the host where the Agent is installed
host_ip	Yes	String	Host IP address
host_os	Yes	String	Host OS
host_nickname	No	String	Host alias
agent_version	No	String	Agent version
agent_type	No	String	Agent type. The value can be: native: local agent, which is installed on the local PC. cloud: cloud agent, which is installed on the cloud.

Response Parameters

Status code: 200

**Table 5** Response body parameters
Parameter	Type	Description
agent	Agent object	Agent details

**Table 6** Agent
Parameter	Type	Description
created_at	String	Time when the Agent was installed
updated_at	String	Time when the Agent was updated
agent_id	String	Agent ID
agent_version	String	Agent version
agent_type	String	Agent type. The value can be: native: local agent, which is installed on the local PC. cloud: cloud agent, which is installed on the cloud.
host_name	String	Name of the host where the Agent is installed
host_nickname	String	Host alias
host_ip	String	Host IP address
host_os	String	Host OS
status	String	Agent status. The value can be: normal: The agent can be used normally. abnormal: The agent is abnormal and needs to be recovered. Some functions are unavailable. uninstall: The agent has been uninstalled or is being upgraded.
last_active_time	String	Time when the Agent was last activated
paths	Array of Path objects	Backup path of the agent

**Table 7** Path
Parameter	Type	Description
id	String	Path ID
status	String	Path status, which can either be available or remove available: The file backup path is available. remove: The file backup path is removed and cannot be used.
agent_id	String	ID of the Agent to which the path belongs
dir_path	String	Path details
exclude_paths	String	List of excluded directories. Use commas (,) to separate multiple paths. NOTE: This feature is in the open beta test (OBT) phase and may be unavailable in some regions.

Example Requests

Automatic agent registration during installation

 POST  https://{endpoint}/v3/f841e01fd2b14e7fa41b6ae7aa6b0594/agents

{
  "agent" : {
    "agent_id" : "489654f2-363b-4ebf-966a-bdf079d97114",
    "host_name" : "ecs-00002",
    "host_ip" : "10.10.0.2",
    "host_os" : "linux",
    "agent_version" : "1.0.0",
    "agent_type" : "native"
  }
}

Example Responses

Status code: 200

{
  "agent" : {
    "created_at" : "2022-01-30T09:28:09.334+00:00",
    "updated_at" : "2022-01-30T09:28:09.334+00:00",
    "agent_id" : "489654f2-363b-4ebf-966a-bdf079d97114",
    "agent_version" : "1.0.0",
    "agent_type" : "native",
    "host_name" : "ecs-0001",
    "host_nickname" : "",
    "host_ip" : "192.168.10.144",
    "host_os" : "linux",
    "status" : "normal",
    "last_active_time" : "2022-01-30T09:28:08.960+00:00"
  }
}