Cloud Platform

Scripting API tasks with the notification parameter

Endpoints in the Cloud Platform API containing a notificationUuid field in returned results enable you to determine the progress and completion status of ongoing tasks. The following general steps describe how you can use the notification parameter:

  1. Issue a Cloud Platform API request to an endpoint that includes a notificationUuid value in the returned result.

  2. Use the returned notificationUuid value in a request to the GET /notifications/{notificationUuid} endpoint to retrieve current information about the status of your task.

Note

The notification API doesn’t display real-time results. It typically returns a response within seconds, but sometimes can take several minutes to reflect the current state of the platform.

Endpoint example values and schemas

An API request to deploy a build artifact to an environment returns a result similar to the following example, which includes a notification value:

{
"message": "Deploying artifact.",
"_links": {
    "self": {
    "href": "https://cloud.acquia.com/api/environments/666-99999999-zzzz-4444-aaaa-444444444444/artifacts/actions/switch"
            },
    "notification": {
    "href": "https://cloud.acquia.com/api/notifications/1111111-7777-4444-aaaa-555555555555"
    }
}
}

You can use the notification value to query the GET /notifications/{notificationUuid} endpoint, which returns data in the following structure:

{
"uuid": "1111111-7777-4444-aaaa-555555555555",
"event": "ApplicationAddedToRecents",
"label": "Application added to recents list",
"description": "\"App Name\" was added to your recent applications list.",
"created_at": "2019-07-29T20:47:13+00:00",
"completed_at": "2019-07-29T20:47:13+00:00",
"status": "completed",
"progress": 100,
"context": {
    "author": {
    "uuid": "55555555-dddd-4444-8888-777777777777",
    "actual_uuid": "55555555-dddd-4444-8888-777777777777"
    },
    "user": {
    "uuids": [
        "55555555-dddd-4444-8888-777777777777"
    ]
    }
},
"_links": {
    "self": {
    "href": "https://cloud.acquia.dev/api/notifications/1111111-7777-4444-aaaa-555555555555"
    },
    "parent": {
    "href": "https://cloud.acquia.dev/api/notifications"
    }
}
}

The response includes (but isn’t limited to) the following fields:

  • progress: An integer between 1 and 100, which is an estimate of the completion percentage of the task.

  • status: A string (either completed or in_progress) describing the completion state of the task.

  • created_at: The creation date and time the notification.

  • started_at: The starting date and time for the task or event tracked by this notification.

  • completed_at: The completion date and time for the task or event tracked by this notification.

For a complete list of returned fields and their definitions, see the Cloud Platform API endpoint documentation.

Example script

The following database creation example script performs the following tasks:

  • Creates a database.

  • Retrieves the notification ID from the response.

  • Determines the status of the notification.

  • Displays a message when the notification indicates the task is complete.

<?php

// This example requires `league/oauth2-client` package.
// Run `composer require league/oauth2-client` before running.
require __DIR__ . '/vendor/autoload.php';

use League\OAuth2\Client\Provider\GenericProvider;
use GuzzleHttp\Client;

// The UUID of an application you want to create the database for.
$applicationUuid = 'APP-UUID';
$dbName = 'test_database_1';
// See https://docs.acquia.com/cloud-platform/develop/api/auth/
// for how to generate a client ID and Secret.
$clientId = 'API-KEY';
$clientSecret = 'API-SECRET';

$provider = new GenericProvider([
    'clientId'                => $clientId,
    'clientSecret'            => $clientSecret,
    'urlAuthorize'            => '',
    'urlAccessToken'          => 'https://accounts.acquia.com/api/auth/oauth/token',
    'urlResourceOwnerDetails' => '',
]);

$client = new Client();
$provider->setHttpClient($client);

echo 'retrieving access token', PHP_EOL;
$accessToken = $provider->getAccessToken('client_credentials');
echo 'access token retrieved', PHP_EOL;

// Generate a request object using the access token.
$request = $provider->getAuthenticatedRequest(
    'POST',
    "https://cloud.acquia.com/api/applications/{$applicationUuid}/databases",
    $accessToken,
    [
        'headers' => ['Content-Type' => 'application/json'],
        'body' => json_encode(['name' => $dbName])
    ]
);

// Send the request.
echo 'requesting db create api', PHP_EOL;
$response = $client->send($request);

echo 'response parsing', PHP_EOL;
$responseBody = json_decode($response->getBody()->getContents(), true);

$notificationLink = $responseBody['_links']['notification']['href'];

$retryCount = 10;

echo 'start watching for notification status at ', $notificationLink, PHP_EOL;
do {
    sleep(5);
    // create notification request.
    $request = $provider->getAuthenticatedRequest(
        'GET',
        $notificationLink,
        $accessToken
    );

    echo 'requesting notification status', PHP_EOL;
    $response = $client->send($request);
    $responseBody = json_decode($response->getBody()->getContents(), true);
    echo 'notification status: ', $responseBody['status'], PHP_EOL;

    if ($responseBody['status'] === 'succeeded') {
        echo 'Successfully created database.';
        exit(0);
    } elseif ($responseBody['status'] === 'failed') {
        echo 'Failed to create database.';
        exit(1);
    } else {
        echo 'retrying notification in 5 sec', PHP_EOL;
        $retryCount--;
        $retry = $retryCount > 0;
    }
} while ($retry);