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:
- Issue a Cloud Platform API request to an endpoint that includes a
notificationUuid
value in the returned result. - Use the returned
notificationUuid
value in a request to the GET /notifications/{notificationUuid} endpoint to retrieve current information about the status of your task.
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 (eithercompleted
orin_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);