There are some methods to operate resources through the Controller Proxy using the APS controller.
In this document:
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 a 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 Resources.
registerResource($resource)
- registers the specified resource on the APS controller.
See Register Resources.
unregisterResource($resource)
- deletes the specified resource from the APS controller.
See Unregister Resources.
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:
$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/');
$apsc = \APS\Request::getController();
$res = $apsc->getResource('73a07050-b4ef-406a-a7fa-3596675a70c7');
$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.
$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).
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);
$apsc = \APS\Request::getController();
$this->title = "New title";
$apsc->updateResource($this);
This method allows you to update any resource belonging to your application.
$apsc = \APS\Request::getController();
$user = $this->users[1];
$apsc->registerResource($user);
$apsc = \APS\Request::getController();
$mailbox = $this->mailboxes[1];
$apsc->unregisterResource($mailbox);
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).
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);
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
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.
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.
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);