Previous topic

General Description

Next topic

Functions and Utilities

DOCUMENTATION
Last updated 22-Sep-2016

Operations with Resources

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

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);

Impersonation through Resource ID

Refer to Impersonation mechanism.

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, i.e. 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:

  1. An application can impersonate only using its own resource.
  2. 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/applications/, 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);