Application Packaging Standard

Last updated 18-Mar-2019

Operations with Resources¶

There are some methods to operate resources through the Controller Proxy using the APS controller.

In this document:

Methods
Getting Resource List
Getting Resource
Linking Resources
Unlinking Resources
Provisioning Resource
Updating Resource
Registering Resource
Unregistering Resource
Register Resource with pre-defined Links
Impersonation through Resource ID
APS Session and resetSession Method
Operations with APS Types
Getting APS Type by Service ID
Sending Raw Request

Methods ¶

Note

To use the methods, you first need to get the Controller Proxy resource as follows:

$apsc = \APS\Request::getController();

Then, the following methods will be available:

getResources() - returns an array of all resources registered by the APS controller, see Getting Resource List.
getResource($id) - requests a resource from the APS controller by resource ID, see Getting Resource Properties.
linkResource($resource1,$linkName,$resource2) - adds resource2 to the link collection linkName in resource1. If $resource2->aps->id is not defined, a new resource is created. See Linking Resources. The method returns the newly created or linked resource.
unlinkResource($resource1,$linkName,$resource2) - removes the link linkName from resource1 to resource2. See Unlinking Resources.
updateResource($resource) - updates the resource with the specified parameters. See Update Resource.
registerResource($resource) - registers the specified resource on the APS controller. See Register Resource.
unregisterResource($resource) - deletes the specified resource from the APS controller. See Unregister Resource.
provisionResource($resource) - provisions the specified resource via the APS controller. See Provisioning Resources.
configureResource($resource) - changes properties of the specified resource via the APS controller. See Resource Configuration.
unprovisionResource($resource) - deletes the specified resource from the APS controller. See Unprovisioning Resources.

Note

Methods updateResource, registerResource, and unregisterResource are applied only to resources of the current Application.

Note

When creating or linking resources for customer, the application must impersonate, the customer, otherwise the created resources will not be visible for the customer in UI.

Some examples of the methods usage:

Getting Resource List ¶

$apsc = \APS\Request::getController();
$resList = $apsc->getResources();

Optional parameters:

$rqlFilter - rql filter, for example: eq(name,'test'),implementing(http://my-company.com/aps/resource/1.0)

$path - resource path. If not specified, default resource path is used

Example:

$apsc = \APS\Request::getController();
$resList = $apsc->getResources('implementing(http://my-company.com/aps/resource/1.0)',
             $apsc->getIo()->resourcePath(). '/ee3b77d3-0022-4961-a936-273abba33724/users/');

Getting Resource ¶

$apsc = \APS\Request::getController();
$res = $apsc->getResource('73a07050-b4ef-406a-a7fa-3596675a70c7');

Linking Resources ¶

$apsc = \APS\Request::getController();
$apsc2 = $apsc->impersonate($this);
$linkName = 'somelink';
$resource1 = $apsc->getResource('73a07050-b4ef-406a-a7fa-3596675a70c7');
$resource2 = $apsc->getResource('cc8d0500-b478-475f-a5f1-358b60c554d4');
$apsc2->linkResource($resource1, $linkName, $resource2);

Each of $resource1 and $resource2 can be either a ResourceBase object, or a ResourceProxy objects, or a string (aps IDs).

If $resource2->aps->id is not set, a new resource will be created and linked with $resource1. Otherwise, the existing two resources will be linked.

This example shows how to create a new resource and link it to the existing resource $tenant:

$apsc = \APS\Request::getController();
$apsc2 = $apsc->impersonate($this);
$tenant = $apsc2->getResource('73a07050-b4ef-406a-a7fa-3596675a70c7');
$vps = \APS\TypeLibrary::newResourceByTypeId('https://my-company.com/mypackage/vps/1.0');
$vps->prop1 = "value1";
$vps->prop2 = "value2";
$apsc2->linkResource($tenant, 'vpses', $vps);

If $resource2->aps->id is not set, a new resource will be created and linked with $resource1.

Unlinking Resources ¶

$apsc = \APS\Request::getController();
$apsc2 = $apsc->impersonate($this);
$linkName = 'somelink';
$apsc2->unlinkResource('73a07050-b4ef-406a-a7fa-3596675a70c7', 'somelink', 'cc8d0500-b478-475f-a5f1-358b60c554d4');

Each of $resource1 and $resource2 can be either a ResourceBase object, or a ResourceProxy object, or a string (aps IDs).

Provisioning Resource ¶

This method allows you to provision a new resource via the APS Controller. Controller will also proxy the operation to the endpoint.

$apsc = \APS\Request::getController();
$apsc2 = $apsc->impersonate($this);
$vps = \APS\TypeLibrary::newResourceByTypeId($this->getTypeByServiceId("vps"));
$vps->prop1 = "value1";
$vps->prop2 = "value2";
$apsc2->provisionResource($vps);

Updating Resource ¶

$apsc = \APS\Request::getController();
$this->title = "New title";
$apsc->updateResource($this);

This method allows you to update any resource belonging to your application.

Registering Resource ¶

$apsc = \APS\Request::getController();
$user = $this->users[1];
$apsc->registerResource($user);

Unregistering Resource ¶

$apsc = \APS\Request::getController();
$mailbox = $this->mailboxes[1];
$apsc->unregisterResource($mailbox);

Register Resource with pre-defined Links ¶

When registering (or provisioning) a new resource with a collection of links, you can specify the list of links within the same REST call, rather than linking resources with separate calls.

To do this, add resources to the links using either the $resource->linkName->add or $resource->linkName->set method.

These methods work for both a collection of links and a singular links.

Example:

$webspaceResource =  \APS\TypeLibrary::newResourceByTypeId($this->getTypeByServiceId("webspace"));

// collection link
foreach ($ipResources as $ip) {
    $webspaceResource->paIpAddresses->add($ip);
}
// singular link
$webspaceResource->plan->set($planResource);

$apsc->registerResource($webspaceResource);

// or: $apsc->provisionResource($webspaceResource);

Or, using the set method:

$webspaceResource =  \APS\TypeLibrary::newResourceByTypeId($this->getTypeByServiceId("webspace"));
$ips = array();
foreach ($ipResources as $ip) {
    $ips[] = $ip;
}

// collection link
$webspaceResource->paIpAddresses->set($ips);
// singular link (in this case 'add' is an alias to the 'set' method)
$webspaceResource->plan->add($planResource);

$apsc->registerResource($webspaceResource);

// or: $apsc->provisionResource($webspaceResource);

The add method accepts an object of the ResourceBase or ResourceProxy class, or a string with resource APS ID.

The set method accepts an object of the ResourceBase or ResourceProxy class, or a string with resource APS ID, or an array of such objects (for a link collection).

Impersonation through Resource ID ¶

Refer to the Impersonation section.

By impersonating, an application receives the rights of the resource owner. When impersonating a customer account, the application can retrieve the customer’s resources, such as domains, subscriptions, etc. Resources created using an impersonated access, will belong to the customer and will be visible for the customer in UI.

If the resource, whose ID is used for the impersonation, belongs to a vendor, that is to a reseller or the provider, then the application impersonates the respective vendor. In this case, you can specify a subscription of a vendor’s customer, where the new resources will be created. In this case, the resources visibility will be in the vendor’s scope, but the created resources owner will be the customer. So, you can link the customer’s resources with vendor’s resources that do not have a reference in the subscription. Example: creating a customer’s sub-domain in a vendor’s domain.

Impersonation through a vendor’s resource and a customer’s subscription adds APS-Resource-ID and APS-Subscription-ID headers to the REST requests from the application to APSC. It can be done since aps-php-runtime-2.2-181.

Input parameters:

Either an object that extends the ResourceBase class or an APS Resource ID.
(Optional) APS resource or APS ID of a customer subscription.

Please remember the following rules about impersonation:

An application can impersonate only using its own resource.
If you use an object as a parameter to this function, make sure the object has aps->id property.

$apsc = \APS\Request::getController();
$apsc2 = $apsc->impersonate($this);
$apsc2->getResources(...

$apsc = \APS\Request::getController();
$apsc2 = $apsc->impersonate($this->aps->id);
$apsc2->getResources(...

// Creating a sub-domain in a vendor's domain

$providerDomain = 'reseller.com';
$apsc = \APS\Request::getController();

$apscI = $apsc->impersonate($this->cloud, $this->subscription);
$dms = $apscI->getResources("implementing('http://parallels.com/aps/types/pa/dns/zone/1.1'),name=reseller.com");
$providerDm = $dm[0];

$dom = \APS\TypeLibrary::newResourceByTypeId('http://parallels.com/aps/types/pa/dns/zone/1.1');
$dom->name = "cust".rand(23456,1023455).'.'.$providerDomain;
$dom->parentDomain->add($providerDm);

$apscI->provisionResource($dom);

APS Session and resetSession Method ¶

If the APS controller sends the APS-Transaction-ID header to the application, PHP runtime includes this header to the response. This APS-Transaction-ID header will be also included when requests are sent via Controller Proxy, as in the examples above.

In case if some operations should be done outside of the transaction, use the resetSession method, as follows:

$apsc = \APS\Request::getController();
$apsc2 = $apsc->impersonate($this);
$apsc2->resetSession();
// further operations on apsc2 will not contain APS-Transaction-ID

If impersonation is not needed, clone the $apsc object:

$apsc = \APS\Request::getController();
$apsc2 = clone $apsc;
$apsc2->resetSession();
// further operations on apsc2 will not contain APS-Transaction-ID

Operations with APS Types ¶

Warning

If you need to use a core type class, do NOT include it directly, as in the following example:

// WRONG EXAMPLE !
// DO NOT DO THIS !
require_once 'aps/2/types/org/standard/aps/types/dns/record/mx/DNSRecordMX.php';
$mx = \org\standard\aps\types\dns\record\mx\DNSRecordMX();

Instead, use the \APS\TypeLibrary::getClassByTypeId function to include the module and receive the class name:

$class = \APS\TypeLibrary::getClassByTypeId("http://aps-standard.org/types/dns/record/mx/1.0");
$mx = new $class();
$mx->aps = new \APS\ResourceMeta('http://aps-standard.org/types/dns/record/mx/1.0');

Or, the shorter variant:

$mx = \APS\TypeLibrary::newResourceByTypeId('http://aps-standard.org/types/dns/record/mx/1.0');

Note

If the type is not found locally, the \APS\TypeLibrary::getClassByTypeId method retrieves it from the APS controller. Module will be included (you don’t need to add require_once). Class name is returned.

Getting APS Type by Service ID ¶

Instead of specifying a resource type with version in a PHP code, like follows:

$newVPS = \APS\TypeLibrary::newResourceByTypeId('http://company.com/app/vps/2.1');

you can use the getTypeByServiceId method.

This method is inherited by the resource class from the ResourceBase class, and is applied to services of current application.

Example:

$newVPS = \APS\TypeLibrary::newResourceByTypeId($this->getTypeByServiceId('vps'));

The service ID parameter is the service ID from application metadata (APP-META.xml).

Note

getTypeByServiceId method is added in PHP Runtime 2.0-383, 2.1-302 and 2.2-115. Use the runtimeVersions annotation to require a particular version.

Sending Raw Request ¶

In case if the methods described above are not sufficient for some reason, you can use the sendRequest method to send a raw request to the APS controller.

Method parameters:

$verb - request type (POST, GET, etc.)

$path - URL path (/aps/2/resources/, /aps/2/apps/, etc.)

$input - string to be sent (default - null)

$contentType - content type of the request (default - application/json)

Examples:

$apsc = \APS\Request::getController();
$admins = $apsc->getIo()->sendRequest(\APS\Proto::GET, "/aps/2/resources/".
                 $this->account->aps->id .
                "/users?implementing(http://parallels.com/aps/types/pa/admin-user/1.0)");

$apsc = \APS\Request::getController();
$apsc->getIo()->sendRequest(\APS\Proto::DELETE, "/aps/2/resources/" . $record->aps->id);

← Module Structure

Functions and Utilities →

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

Operations with Resources¶

Methods ¶

Getting Resource List ¶

Getting Resource ¶

Linking Resources ¶

Unlinking Resources ¶

Provisioning Resource ¶

Updating Resource ¶

Registering Resource ¶

Unregistering Resource ¶

Register Resource with pre-defined Links ¶

Impersonation through Resource ID ¶

APS Session and resetSession Method ¶

Operations with APS Types ¶

Getting APS Type by Service ID ¶

Sending Raw Request ¶