Previous topic

General Description

Next topic

Functions and Utilities

DOCUMENTATION
Last updated 11-Aug-2016

Operations with Resources

There are some methods for operations with 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:

<?php
   ...
      $apsc = \APS\Request::getController();

Then, the following methods will be available:

  • getResources() - returns an array of all resources registered on 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. Returns newly created or linked Resource.
  • unlinkResource($resource1,$linkName,$resource2) - removes 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) - provision resource via the APS controller, see Provisioning Resources.
  • configureResource($resource) - changing 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, unregisterResource are applied only to resources of the current Application.

Note

When creating or linking resources for customer, it is necessary to impersonate, otherwise created resources will not be visible for customer in UI.

Some examples of the methods usage:

Getting Resource List

<?php
   ...
      $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:

<?php
   ...
   $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

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

Linking Resources

<?php
   ...
   $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 ResourceBase or ResourceProxy objects, or strings (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 links it to existing resource $tenant:

<?php
   ...
   $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

<?php
   ...
   $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 ResourceBase or ResourceProxy objects, or strings (aps IDs).

Provisioning Resource

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

<?php
  ...
   $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

<?php
   ...
      $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

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

Unregistering Resource

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

Impersonation through Resource ID

Refer to Impersonation mechanism.

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

Input parameters: either an object that extends the ResourceBase class, or a Resource APS ID.

Impersonation is based on the following rules:

  1. An application can impersonate only its own resource.
  2. If you use an object as a parameter in the impersonate function, make sure this object has the aps->id property.
<?php
   ...
      $apsc = \APS\Request::getController();
          $apsc2 = $apsc->impersonate($this);
          $apsc2->getResources(...
<?php
   ...
      $apsc = \APS\Request::getController();
          $apsc2 = $apsc->impersonate($this->aps->id);
          $apsc2->getResources(...

APS Session and resetSession method

If APS Controller sends 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 resetSession method, as follows:

<?php
  $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 $apsc object:

<?php
  $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:

<?php
   ...
   // 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:

<?php
   ...
   $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:

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

Note

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

Getting APS type by service ID

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

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

you can use method getTypeByServiceId.

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

Example:

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

Service Id parameter is the service id from application metadata (APP-META.xml).

Note

getTypeByServiceId method is added in PHP Runtime 2.0-382, 2.1-301 and 2.2-112. Use runtimeVersions annotation to require particular version.

Sending Raw Request

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

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