The get operation is used to retrieve the following FTP account settings:

  • Name/ login
  • Home directory
  • Quota on using disk space
  • Permissions for home directory
  • ID of the site on which FTP account exists

You can retrieve information on several FTP accounts in a single get operation by defining the filtering rule. Use the blank filter (<filter/>) parameter to get information about all FTP accounts on all sites for the user identified by credentials from HTTP header.

Request Packet Structure

A request XML packet retrieving information on FTP account settings includes the get operation node:

<packet>
<ftp-user>
   <get>
   ...
   </get>
</ftp-user>
</packet>

The get node is presented by the FtpUserGetInputType complex type (ftpuser.xsd). The node has the following graphical representation:

image 35346

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.

  • The filter node is required. It indicates FTP accounts which settings are to be retrieved with the request packet. Data type: FtpUserFilterType (ftpuser.xsd). For information on this node structure, refer to Available Filters.

Remarks

Within one get operation you can retrieve information on FTP accounts using only one filtering rule: account IDs, account names, site IDs, or site names. However, you can always use several different filtering rules within one packet by including to it several get nodes.

Response Packet Structure

The get node of the output XML packet is structured as follows:

image 70043

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.

  • The result node is required. It wraps the response received from the server. Data type: FtpUserGetResultType (ftpuser.xsd).

  • The status node is required. It specifies the execution status of the get operation. Data type: result_status. Allowed values: ok | error.

  • The errcode node is optional. It is used to return the error code when the get operation fails. Data type: unsignedInt.

  • The errtext node is optional. It is used to return the error message if the get operation fails. Data type: string.

  • The filter-id node is optional. It is required if the get operation succeeds. It returns the filtering rule. For more information, refer to the Available Filters section. Data type: anySimple.

  • The id node is optional. It is required if the get operation succeeds. It returns the unique identifier of the FTP account which settings are retrieved in the response packet. Data type: integer.

  • The name node is optional. It is required if the get operation succeeds. It specifies the name under which the FTP account is known in Plesk, and the account login. Data type: string.

  • The home node is optional. It is required if the get operation succeeds. It specifies the home directory of the FTP account, i.e., the directory access to which is granted for the account user. Data type: string.

  • The quota node is optional. It is required if the get operation succeeds. It specifies the maximum total size of files and folders (in bytes) that the FTP account user can create in or upload to the home directory. Data type: integer.

  • The permissions node is optional. It is required if the get operation succeeds. It specifies the FTP account permissions for home directory. For more information, refer to section FTP Account Permissions. Data type: FtpUserPermissions.

    Note: Note: The node is displayed only on Windows.

  • The webspace-id node is optional. It is required if the get operation succeeds. It specifies the ID of the site on which the FTP account exists. Data type: integer.

Remarks

In case when a site was specified as filtering rule in a request packet, and there are no FTP accounts existing on that site, response packet does not contain the name, home, quota, permissions and site-id nodes.

Samples

Retrieving information on a single FTP account

This packet retrieves information on FTP account with ID 16.

<packet>
<ftp-user>
<get>
   <filter>
      <id>16</id>
   </filter>
</get>
</ftp-user>
</packet>

Response:

<packet>
<ftp-user>
<get>
   <result>
      <status>ok</status>
      <filter-id>16</filter-id>
      <id>16</id>
      <name>jenny</name>
      <home></home>
      <quota>-1</quota>
      <permissions>
         <read>false</read>
         <write>false</write>
      </permissions>
      <webspace-id>1</webspace-id>
   </result>
</get>
</ftp-user>
</packet>

Retrieving information on multiple FTP accounts

This packet retrieves information on FTP accounts with names photo1 and photo3, and on all FTP accounts existing on site with ID 34.

<packet>
<ftp-user>
<get>
   <filter>
      <name>photo1</name>
      <name>photo3</name>
   </filter>
</get>
<get>
   <filter>
      <site-id>34</site-id>
   </filter>
</get>
</ftp-user>
</packet>

Response:

<packet>
<ftp-user>
<get>
   <result>
      <status>ok</status>
      <filter-id>photo1</filter-id>
      <id>7</id>
      <name>photo1</name>
      <home>/private/photoshare/Incoming</home>
      <quota>104857600</quota>
      <permissions>
         <read>true</read>
         <write>true</write>
      </permissions>
      <webspace-id>2</webspace-id>
   </result>
   <result>
      <status>ok</status>
      <filter-id>photo3</filter-id>
      <id>9</id>
      <name>photo3</name>
      <home>/private/photoshare/Incoming</home>
      <quota>0</quota>
      <permissions>
         <read>true</read>
         <write>false</write>
      </permissions>
      <webspace-id>2</webspace-id>
   </result>
</get>
<get>
   <result>
      <status>ok</status>
      <filter-id>34</filter-id>
   </result>
</get>
</ftp-user>
</packet>

Retrieving information on all FTP accounts existing on all sites created in Plesk

This packet retrieves information on all FTP accounts existing on all sites created in Plesk if it is sent with Plesk Administrator credentials in the packet HTTP headers, or on all sites belonging to a Plesk customer whose credentials are specified in the HTTP headers.

<packet>
<ftp-user>
<get>
   <filter/>
</get>
</ftp-user>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <ftp-user>
    <get>
      <result>
        <status>ok</status>
        <filter-id>1</filter-id>
        <id>1</id>
        <name>ftpuser1</name>
        <home>/</home>
        <webspace-id>1</webspace-id>
      </result>
      <result>
        <status>ok</status>
        <filter-id>2</filter-id>
        <id>2</id>
        <name>photo1</name>
        <home>/private/photoshare/Incoming</home>
        <webspace-id>6</webspace-id>
      </result>
      <result>
        <status>ok</status>
        <filter-id>3</filter-id>
        <id>3</id>
        <name>photo2</name>
        <home>/private/photoshare/Incoming</home>
        <webspace-id>6</webspace-id>
      </result>
      <result>
        <status>ok</status>
        <filter-id>4</filter-id>
        <id>4</id>
        <name>photo3</name>
        <home>/private/photoshare/Incoming</home>
        <webspace-id>6</webspace-id>
      </result>
    </get>
  </ftp-user>
</packet>