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:

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.

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

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.

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

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.

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

Get Answers

Search

Search

Endpoint example values and schemas

Example script

Endpoint example values and schemas

Example script

Endpoint example values and schemas

Example script

Did not find what you were looking for?

Did not find what you were looking for?