SDK for PHP V3

AWS Sustainability 2018-05-10

Client: Aws\Sustainability\SustainabilityClient
Service ID: sustainability
Version: 2018-05-10

This page describes the parameters and results for the operations of the AWS Sustainability (2018-05-10), and shows how to use the Aws\Sustainability\SustainabilityClient object to call the described operations. This documentation is specific to the 2018-05-10 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

GetEstimatedCarbonEmissions ( array $params = [] )
Returns estimated carbon emission values based on customer grouping and filtering parameters.
GetEstimatedCarbonEmissionsDimensionValues ( array $params = [] )
Returns the possible dimension values available for a customer's account.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

GetEstimatedCarbonEmissions
GetEstimatedCarbonEmissionsDimensionValues

Operations

GetEstimatedCarbonEmissions 

$result = $client->getEstimatedCarbonEmissions([/* ... */]);
$promise = $client->getEstimatedCarbonEmissionsAsync([/* ... */]);

Returns estimated carbon emission values based on customer grouping and filtering parameters. We recommend using pagination to ensure that the operation returns quickly and successfully.

Parameter Syntax

$result = $client->getEstimatedCarbonEmissions([
    'EmissionsTypes' => ['<string>', ...],
    'FilterBy' => [
        'Dimensions' => [
            '<Dimension>' => ['<string>', ...],
            // ...
        ],
    ],
    'Granularity' => 'YEARLY_CALENDAR|YEARLY_FISCAL|QUARTERLY_CALENDAR|QUARTERLY_FISCAL|MONTHLY',
    'GranularityConfiguration' => [
        'FiscalYearStartMonth' => <integer>,
    ],
    'GroupBy' => ['<string>', ...],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'TimePeriod' => [ // REQUIRED
        'End' => <integer || string || DateTime>, // REQUIRED
        'Start' => <integer || string || DateTime>, // REQUIRED
    ],
]);

Parameter Details

Members
EmissionsTypes
Type: Array of strings

The emission types to include in the results. If absent, returns TOTAL_LBM_CARBON_EMISSIONS and TOTAL_MBM_CARBON_EMISSIONS emissions types.

FilterBy
Type: FilterExpression structure

The criteria for filtering estimated carbon emissions.

Granularity
Type: string

The time granularity for the results. If absent, uses MONTHLY time granularity.

GranularityConfiguration
Type: GranularityConfiguration structure

Configuration for fiscal year calculations when using YEARLY_FISCAL or QUARTERLY_FISCAL granularity.

GroupBy
Type: Array of strings

The dimensions available for grouping estimated carbon emissions.

MaxResults
Type: int

The maximum number of results to return in a single call. Default is 40.

NextToken
Type: string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

TimePeriod
Required: Yes
Type: TimePeriod structure

The date range for fetching estimated carbon emissions.

Result Syntax

[
    'NextToken' => '<string>',
    'Results' => [
        [
            'DimensionsValues' => ['<string>', ...],
            'EmissionsValues' => [
                '<EmissionsType>' => [
                    'Unit' => 'MTCO2e',
                    'Value' => <float>,
                ],
                // ...
            ],
            'ModelVersion' => '<string>',
            'TimePeriod' => [
                'End' => <DateTime>,
                'Start' => <DateTime>,
            ],
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

The pagination token indicating there are additional pages available. You can use the token in a following request to fetch the next set of results.

Results
Required: Yes
Type: Array of EstimatedCarbonEmissions structures

The result of the requested inputs.

Errors

ValidationException:

The input fails to satisfy the constraints specified by an Amazon Web Services service.

InternalServerException:

The request processing has failed because of an unknown error, exception, or failure.

AccessDeniedException:

You do not have sufficient access to perform this action.

ThrottlingException:

The request was denied due to request throttling.

Examples

Example 1: GetEstimatedCarbonEmissionsSuccess 
$result = $client->getEstimatedCarbonEmissions([
    'EmissionsTypes' => [
        'TOTAL_LBM_CARBON_EMISSIONS',
        'TOTAL_MBM_CARBON_EMISSIONS',
        'TOTAL_SCOPE_1_CARBON_EMISSIONS',
        'TOTAL_SCOPE_2_LBM_CARBON_EMISSIONS',
        'TOTAL_SCOPE_2_MBM_CARBON_EMISSIONS',
        'TOTAL_SCOPE_3_LBM_CARBON_EMISSIONS',
        'TOTAL_SCOPE_3_MBM_CARBON_EMISSIONS',
    ],
    'Granularity' => 'MONTHLY',
    'GroupBy' => [
        'SERVICE',
    ],
    'TimePeriod' => [
        'End' => ,
        'Start' => ,
    ],
]);

Result syntax:

[
    'Results' => [
        [
            'DimensionsValues' => [
                'SERVICE' => 'AmazonEC2',
            ],
            'EmissionsValues' => [
                'TOTAL_LBM_CARBON_EMISSIONS' => [
                    'Unit' => 'MTCO2e',
                    'Value' => 1,
                ],
                'TOTAL_MBM_CARBON_EMISSIONS' => [
                    'Unit' => 'MTCO2e',
                    'Value' => 1,
                ],
                'TOTAL_SCOPE_1_CARBON_EMISSIONS' => [
                    'Unit' => 'MTCO2e',
                    'Value' => 1,
                ],
                'TOTAL_SCOPE_2_LBM_CARBON_EMISSIONS' => [
                    'Unit' => 'MTCO2e',
                    'Value' => 1,
                ],
                'TOTAL_SCOPE_2_MBM_CARBON_EMISSIONS' => [
                    'Unit' => 'MTCO2e',
                    'Value' => 1,
                ],
                'TOTAL_SCOPE_3_LBM_CARBON_EMISSIONS' => [
                    'Unit' => 'MTCO2e',
                    'Value' => 1,
                ],
                'TOTAL_SCOPE_3_MBM_CARBON_EMISSIONS' => [
                    'Unit' => 'MTCO2e',
                    'Value' => 1,
                ],
            ],
            'ModelVersion' => 'v3.0.0',
            'TimePeriod' => [
                'End' => ,
                'Start' => ,
            ],
        ],
    ],
]

GetEstimatedCarbonEmissionsDimensionValues 

$result = $client->getEstimatedCarbonEmissionsDimensionValues([/* ... */]);
$promise = $client->getEstimatedCarbonEmissionsDimensionValuesAsync([/* ... */]);

Returns the possible dimension values available for a customer's account. We recommend using pagination to ensure that the operation returns quickly and successfully.

Parameter Syntax

$result = $client->getEstimatedCarbonEmissionsDimensionValues([
    'Dimensions' => ['<string>', ...], // REQUIRED
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'TimePeriod' => [ // REQUIRED
        'End' => <integer || string || DateTime>, // REQUIRED
        'Start' => <integer || string || DateTime>, // REQUIRED
    ],
]);

Parameter Details

Members
Dimensions
Required: Yes
Type: Array of strings

The dimensions available for grouping estimated carbon emissions.

MaxResults
Type: int

The maximum number of results to return in a single call. Default is 40.

NextToken
Type: string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

TimePeriod
Required: Yes
Type: TimePeriod structure

The date range for fetching the dimension values.

Result Syntax

[
    'NextToken' => '<string>',
    'Results' => [
        [
            'Dimension' => 'USAGE_ACCOUNT_ID|REGION|SERVICE',
            'Value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

The pagination token indicating there are additional pages available. You can use the token in a following request to fetch the next set of results.

Results
Type: Array of DimensionEntry structures

The list of possible dimensions over which the emissions data is aggregated.

Errors

ValidationException:

The input fails to satisfy the constraints specified by an Amazon Web Services service.

InternalServerException:

The request processing has failed because of an unknown error, exception, or failure.

AccessDeniedException:

You do not have sufficient access to perform this action.

ThrottlingException:

The request was denied due to request throttling.

Examples

Example 1: GetEstimatedCarbonEmissionsDimensionValuesSuccess 
$result = $client->getEstimatedCarbonEmissionsDimensionValues([
    'Dimensions' => [
        'REGION',
        'SERVICE',
        'USAGE_ACCOUNT_ID',
    ],
    'TimePeriod' => [
        'End' => ,
        'Start' => ,
    ],
]);

Result syntax:

[
    'Results' => [
        [
            'Dimension' => 'SERVICE',
            'Value' => 'AmazonEC2',
        ],
        [
            'Dimension' => 'SERVICE',
            'Value' => 'AmazonS3',
        ],
        [
            'Dimension' => 'SERVICE',
            'Value' => 'AmazonCloudFront',
        ],
        [
            'Dimension' => 'REGION',
            'Value' => 'global',
        ],
        [
            'Dimension' => 'REGION',
            'Value' => 'us-east-1',
        ],
        [
            'Dimension' => 'REGION',
            'Value' => 'us-west-2',
        ],
        [
            'Dimension' => 'USAGE_ACCOUNT_ID',
            'Value' => '111222333444',
        ],
    ],
]

Shapes

AccessDeniedException

Description

You do not have sufficient access to perform this action.

Members
Message
Required: Yes
Type: string

DimensionEntry

Description

Represents a dimension and its corresponding value.

Members
Dimension
Required: Yes
Type: string

The dimension type that categorizes this entry.

Value
Required: Yes
Type: string

The value for the specified dimension. Valid values vary based on the dimension type (e.g., us-east-1 for the REGION dimension, AmazonEC2 for the SERVICE dimension).

Emissions

Description

Represents a carbon emissions quantity with its value and unit of measurement.

Members
Unit
Required: Yes
Type: string

The unit of measurement for the emissions value.

Value
Required: Yes
Type: double

The numeric value of the emissions quantity.

EstimatedCarbonEmissions

Description

Contains estimated carbon emissions data for a specific time period and dimension grouping.

Members
DimensionsValues
Required: Yes
Type: Associative array of custom strings keys (Dimension) to strings

The dimensions used to group emissions values.

EmissionsValues
Required: Yes
Type: Associative array of custom strings keys (EmissionsType) to Emissions structures

The emissions values for the requested emissions types.

ModelVersion
Required: Yes
Type: string

The semantic version-formatted string that indicates the methodology version used to calculate the emission values.

The AWS Sustainability service reflects the most recent model version for every month. You will not see two entries for the same month with different ModelVersion values. To track the evolution of the methodology and compare emission values from previous versions, we recommend creating a Data Export.

TimePeriod
Required: Yes
Type: TimePeriod structure

The reporting period for emission values.

FilterExpression

Description

Filters emission values by specific dimension values.

Members
Dimensions
Type: Associative array of custom strings keys (Dimension) to stringss

Filters emission values by specific dimension values.

GranularityConfiguration

Description

Contains configuration for the fiscal year granularities (e.g., YEARLY_FISCAL, QUARTERLY_FISCAL.

Members
FiscalYearStartMonth
Type: int

The month (1-12) when the fiscal year begins. Used for YEARLY_FISCAL and QUARTERLY_FISCAL granularity. Defaults to 1 (January).

InternalServerException

Description

The request processing has failed because of an unknown error, exception, or failure.

Members
Message
Required: Yes
Type: string

ThrottlingException

Description

The request was denied due to request throttling.

Members
Message
Required: Yes
Type: string

TimePeriod

Description

Represents a duration of time defined by start and end timestamps.

Members
End
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The end (exclusive) of the time period. ISO-8601 formatted timestamp, for example: YYYY-MM-DDThh:mm:ss.sssZ

Start
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The start (inclusive) of the time period. ISO-8601 formatted timestamp, for example: YYYY-MM-DDThh:mm:ss.sssZ

ValidationException

Description

The input fails to satisfy the constraints specified by an Amazon Web Services service.

Members
Message
Required: Yes
Type: string