Both zone template records and site or site alias zone records can be retrieved using the get_rec operation. You can retrieve multiple records in a single get_rec operation using filtering rules. For more information about filters, refer to the Available Filters section.

Request Packet Structure

A request XML packet retrieving a DNS record from Plesk database includes the get_rec operation node:

<packet>
    <dns>
        <get_rec>
            ...
        </get_rec>
    </dns>
</packet>

The graphical representation of the get_rec node is as follows:

image 34839

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

  • The filter node is required. It specifies the filtering rule. For more information, refer to the Available Filters section. Data type: dnsSelectionFilterType (dns_input.xsd) .
  • The template node is optional. If present, only DNS zone template records are available for retrieving. In this case filter children cannot be specified as a filtering rule. Data type: none.

Note: If you leave the filter node blank (<filter/>), all resource records (zone template records or zone records depending on presence of the template node in the request packet) will be retrieved.

You can retrieve multiple DNS records in a single packet. Add as many get_rec operations as the number of different filtering rules.

<dns>
   <get_rec>
   ...
   </get_rec>
...
   <get_rec>
   ...
   </get_rec>

</dns>

Note: When creating request packets, put nodes and elements in the order they follow in the packet structure.

Response Packet Structure

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

image 38240

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

  • The result node is optional. It is required if the operation get_rec succeeds, and the data set retrieved from the server is not empty. Data type: resultType (common.xsd).

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

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

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

  • The id node is required if the get_rec operation has succeeded. Returns the unique identifier of the DNS record. Data type: integer.

  • The data node is optional. It is required if the get_rec operation has succeeded. Data type: dnsRecord (dns_input.xsd). The node is structured as follows:

    image 38241

    • The site-id node is optional. If specified, the DNS record is retrieved from zone parameters for the site with the corresponding ID. Data type: integer.
    • The site-alias-id node is optional. If specified, the DNS record is retrieved from zone parameters for the site alias with the corresponding ID. Data type: integer.
    • The type node is optional. It is required if the operation succeeded. It specifies the type of the DNS record. For more information about DNS types, please visit the Adding a DNS Record section. Data type: string. Allowed values: A | NS | CNAME | MX | PTR | TXT | SOA | AXFR | SRV | AAAA | DS.
    • The host node is optional. It is required if the operation succeeded. It specifies the IP address or name of a host, that will be used by DNS. Data type: string.
    • The value node is optional. It is required if the operation succeeded. It specifies the value that will be linked with the host value. Data type: string.
    • The opt node is optional. It holds optional information about the DNS record. Data type: string.

Samples

Retrieving a single DNS record

This request packet retrieves the DNS record with ID 8.

<packet>
    <dns>
        <get_rec>
            <filter>
                <id>8</id>
            </filter>
        </get_rec>
    </dns>
</packet>

Response:

<packet>
    <dns>
        <get_rec>
            <result>
                <status>ok</status>
                <id>8</id>
                <data>
                    <site-id>8</site-id>
                    <type>NS</type>
                    <host>Mysite.com</host>
                    <value>ns.Mysite.com</value>
                    <opt/>
                </data>
            </result>
        </get_rec>
    </dns>
</packet>

If the DNS record with ID 8 was not found on the server, the response looks as follows:

<packet>
    <dns>
        <get_rec>
     </get_rec>
    </dns>
</packet>

Retrieving multiple DNS records

This request packet retrieves zone preferences of the site with ID 8.

<packet>
    <dns>
        <get_rec>
            <filter>
                <site-id>8</site-id>
            </filter>
        </get_rec>
    </dns>
</packet>

Response:

<packet>
    <dns>
        <get_rec>
            <result>
                <status>ok</status>
                <id>18</id>
                <data>
                    <site-id>8</site-id>
                    <type>NS</type>
                    <host>Mysite.com</host>
                    <value>ns.Mysite.com</value>
                    <opt/>
                </data>
            </result>
        </get_rec>
        <get_rec>
            <result>
                <status>ok</status>
                <id>19</id>
                <data>
                    <site-id>8</site-id>
                    <type>PTR</type>
                    <host/>
                    <value>Mysite.com</value>
                    <opt/>
                </data>
            </result>
        </get_rec>
    </dns>
</packet>

If the site with ID 8 was not found on the server, the response from the server looks as follows:

<packet>
    <dns>
        <get_rec>
      </get_rec>
    </dns>
</packet>