AWS Health APIs and Notifications 2016-08-04
- Client: Aws\Health\HealthClient
- Service ID: health
- Version: 2016-08-04
This page describes the parameters and results for the operations of the AWS Health APIs and Notifications (2016-08-04), and shows how to use the Aws\Health\HealthClient object to call the described operations. This documentation is specific to the 2016-08-04 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 */).
- DescribeAffectedEntities ( array $params = [] )
Returns a list of entities that have been affected by the specified events, based on the specified filter criteria.
- DescribeEntityAggregates ( array $params = [] )
Returns the number of entities that are affected by each of the specified events.
- DescribeEventAggregates ( array $params = [] )
Returns the number of events of each event type (issue, scheduled change, and account notification).
- DescribeEventDetails ( array $params = [] )
Returns detailed information about one or more specified events.
- DescribeEventTypes ( array $params = [] )
Returns the event types that meet the specified filter criteria.
- DescribeEvents ( array $params = [] )
Returns information about events that meet the specified filter criteria.
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:
Operations
DescribeAffectedEntities
$result = $client->describeAffectedEntities([/* ... */]); $promise = $client->describeAffectedEntitiesAsync([/* ... */]);
Returns a list of entities that have been affected by the specified events, based on the specified filter criteria. Entities can refer to individual customer resources, groups of customer resources, or any other construct, depending on the AWS service. Events that have impact beyond that of the affected entities, or where the extent of impact is unknown, include at least one entity indicating this.
At least one event ARN is required. Results are sorted by the lastUpdatedTime of the entity, starting with the most recent.
Parameter Syntax
$result = $client->describeAffectedEntities([
'filter' => [ // REQUIRED
'entityArns' => ['<string>', ...],
'entityValues' => ['<string>', ...],
'eventArns' => ['<string>', ...], // REQUIRED
'lastUpdatedTimes' => [
[
'from' => <integer || string || DateTime>,
'to' => <integer || string || DateTime>,
],
// ...
],
'statusCodes' => ['<string>', ...],
'tags' => [
['<string>', ...],
// ...
],
],
'locale' => '<string>',
'maxResults' => <integer>,
'nextToken' => '<string>',
]);
Parameter Details
Members
- filter
-
- Required: Yes
- Type: EntityFilter structure
Values to narrow the results returned. At least one event ARN is required.
- locale
-
- Type: string
The locale (language) to return information in. English (en) is the default and the only supported value at this time.
- maxResults
-
- Type: int
The maximum number of items to return in one batch, between 10 and 100, inclusive.
- nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Result Syntax
[
'entities' => [
[
'awsAccountId' => '<string>',
'entityArn' => '<string>',
'entityUrl' => '<string>',
'entityValue' => '<string>',
'eventArn' => '<string>',
'lastUpdatedTime' => <DateTime>,
'statusCode' => 'IMPAIRED|UNIMPAIRED|UNKNOWN',
'tags' => ['<string>', ...],
],
// ...
],
'nextToken' => '<string>',
]
Result Details
Members
- entities
-
- Type: Array of AffectedEntity structures
The entities that match the filter criteria.
- nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Errors
-
InvalidPaginationToken:
The specified pagination token (
nextToken) is not valid. -
UnsupportedLocale:
The specified locale is not supported.
DescribeEntityAggregates
$result = $client->describeEntityAggregates([/* ... */]); $promise = $client->describeEntityAggregatesAsync([/* ... */]);
Returns the number of entities that are affected by each of the specified events. If no events are specified, the counts of all affected entities are returned.
Parameter Syntax
$result = $client->describeEntityAggregates([
'eventArns' => ['<string>', ...],
]);
Parameter Details
Members
- eventArns
-
- Type: Array of strings
A list of event ARNs (unique identifiers). For example:
"arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-CDE456", "arn:aws:health:us-west-1::event/EBS/AWS_EBS_LOST_VOLUME/AWS_EBS_LOST_VOLUME_CHI789_JKL101"
Result Syntax
[
'entityAggregates' => [
[
'count' => <integer>,
'eventArn' => '<string>',
],
// ...
],
]
Result Details
Members
- entityAggregates
-
- Type: Array of EntityAggregate structures
The number of entities that are affected by each of the specified events.
Errors
There are no errors described for this operation.
DescribeEventAggregates
$result = $client->describeEventAggregates([/* ... */]); $promise = $client->describeEventAggregatesAsync([/* ... */]);
Returns the number of events of each event type (issue, scheduled change, and account notification). If no filter is specified, the counts of all events in each category are returned.
Parameter Syntax
$result = $client->describeEventAggregates([
'aggregateField' => 'eventTypeCategory', // REQUIRED
'filter' => [
'availabilityZones' => ['<string>', ...],
'endTimes' => [
[
'from' => <integer || string || DateTime>,
'to' => <integer || string || DateTime>,
],
// ...
],
'entityArns' => ['<string>', ...],
'entityValues' => ['<string>', ...],
'eventArns' => ['<string>', ...],
'eventStatusCodes' => ['<string>', ...],
'eventTypeCategories' => ['<string>', ...],
'eventTypeCodes' => ['<string>', ...],
'lastUpdatedTimes' => [
[
'from' => <integer || string || DateTime>,
'to' => <integer || string || DateTime>,
],
// ...
],
'regions' => ['<string>', ...],
'services' => ['<string>', ...],
'startTimes' => [
[
'from' => <integer || string || DateTime>,
'to' => <integer || string || DateTime>,
],
// ...
],
'tags' => [
['<string>', ...],
// ...
],
],
'maxResults' => <integer>,
'nextToken' => '<string>',
]);
Parameter Details
Members
- aggregateField
-
- Required: Yes
- Type: string
The only currently supported value is
eventTypeCategory. - filter
-
- Type: EventFilter structure
Values to narrow the results returned.
- maxResults
-
- Type: int
The maximum number of items to return in one batch, between 10 and 100, inclusive.
- nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Result Syntax
[
'eventAggregates' => [
[
'aggregateValue' => '<string>',
'count' => <integer>,
],
// ...
],
'nextToken' => '<string>',
]
Result Details
Members
- eventAggregates
-
- Type: Array of EventAggregate structures
The number of events in each category that meet the optional filter criteria.
- nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Errors
-
InvalidPaginationToken:
The specified pagination token (
nextToken) is not valid.
DescribeEventDetails
$result = $client->describeEventDetails([/* ... */]); $promise = $client->describeEventDetailsAsync([/* ... */]);
Returns detailed information about one or more specified events. Information includes standard event data (region, service, etc., as returned by DescribeEvents), a detailed event description, and possible additional metadata that depends upon the nature of the event. Affected entities are not included; to retrieve those, use the DescribeAffectedEntities operation.
If a specified event cannot be retrieved, an error message is returned for that event.
Parameter Syntax
$result = $client->describeEventDetails([
'eventArns' => ['<string>', ...], // REQUIRED
'locale' => '<string>',
]);
Parameter Details
Members
- eventArns
-
- Required: Yes
- Type: Array of strings
A list of event ARNs (unique identifiers). For example:
"arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-CDE456", "arn:aws:health:us-west-1::event/EBS/AWS_EBS_LOST_VOLUME/AWS_EBS_LOST_VOLUME_CHI789_JKL101" - locale
-
- Type: string
The locale (language) to return information in. English (en) is the default and the only supported value at this time.
Result Syntax
[
'failedSet' => [
[
'errorMessage' => '<string>',
'errorName' => '<string>',
'eventArn' => '<string>',
],
// ...
],
'successfulSet' => [
[
'event' => [
'arn' => '<string>',
'availabilityZone' => '<string>',
'endTime' => <DateTime>,
'eventTypeCategory' => 'issue|accountNotification|scheduledChange',
'eventTypeCode' => '<string>',
'lastUpdatedTime' => <DateTime>,
'region' => '<string>',
'service' => '<string>',
'startTime' => <DateTime>,
'statusCode' => 'open|closed|upcoming',
],
'eventDescription' => [
'latestDescription' => '<string>',
],
'eventMetadata' => ['<string>', ...],
],
// ...
],
]
Result Details
Members
- failedSet
-
- Type: Array of EventDetailsErrorItem structures
Error messages for any events that could not be retrieved.
- successfulSet
-
- Type: Array of EventDetails structures
Information about the events that could be retrieved.
Errors
-
UnsupportedLocale:
The specified locale is not supported.
DescribeEventTypes
$result = $client->describeEventTypes([/* ... */]); $promise = $client->describeEventTypesAsync([/* ... */]);
Returns the event types that meet the specified filter criteria. If no filter criteria are specified, all event types are returned, in no particular order.
Parameter Syntax
$result = $client->describeEventTypes([
'filter' => [
'eventTypeCategories' => ['<string>', ...],
'eventTypeCodes' => ['<string>', ...],
'services' => ['<string>', ...],
],
'locale' => '<string>',
'maxResults' => <integer>,
'nextToken' => '<string>',
]);
Parameter Details
Members
- filter
-
- Type: EventTypeFilter structure
Values to narrow the results returned.
- locale
-
- Type: string
The locale (language) to return information in. English (en) is the default and the only supported value at this time.
- maxResults
-
- Type: int
The maximum number of items to return in one batch, between 10 and 100, inclusive.
- nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Result Syntax
[
'eventTypes' => [
[
'category' => 'issue|accountNotification|scheduledChange',
'code' => '<string>',
'service' => '<string>',
],
// ...
],
'nextToken' => '<string>',
]
Result Details
Members
- eventTypes
-
- Type: Array of EventType structures
A list of event types that match the filter criteria. Event types have a category (
issue,accountNotification, orscheduledChange), a service (for example,EC2,RDS,DATAPIPELINE,BILLING), and a code (in the formatAWS_SERVICE_DESCRIPTION; for example,AWS_EC2_SYSTEM_MAINTENANCE_EVENT). - nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Errors
-
InvalidPaginationToken:
The specified pagination token (
nextToken) is not valid. -
UnsupportedLocale:
The specified locale is not supported.
DescribeEvents
$result = $client->describeEvents([/* ... */]); $promise = $client->describeEventsAsync([/* ... */]);
Returns information about events that meet the specified filter criteria. Events are returned in a summary form and do not include the detailed description, any additional metadata that depends on the event type, or any affected resources. To retrieve that information, use the DescribeEventDetails and DescribeAffectedEntities operations.
If no filter criteria are specified, all events are returned. Results are sorted by lastModifiedTime, starting with the most recent.
Parameter Syntax
$result = $client->describeEvents([
'filter' => [
'availabilityZones' => ['<string>', ...],
'endTimes' => [
[
'from' => <integer || string || DateTime>,
'to' => <integer || string || DateTime>,
],
// ...
],
'entityArns' => ['<string>', ...],
'entityValues' => ['<string>', ...],
'eventArns' => ['<string>', ...],
'eventStatusCodes' => ['<string>', ...],
'eventTypeCategories' => ['<string>', ...],
'eventTypeCodes' => ['<string>', ...],
'lastUpdatedTimes' => [
[
'from' => <integer || string || DateTime>,
'to' => <integer || string || DateTime>,
],
// ...
],
'regions' => ['<string>', ...],
'services' => ['<string>', ...],
'startTimes' => [
[
'from' => <integer || string || DateTime>,
'to' => <integer || string || DateTime>,
],
// ...
],
'tags' => [
['<string>', ...],
// ...
],
],
'locale' => '<string>',
'maxResults' => <integer>,
'nextToken' => '<string>',
]);
Parameter Details
Members
- filter
-
- Type: EventFilter structure
Values to narrow the results returned.
- locale
-
- Type: string
The locale (language) to return information in. English (en) is the default and the only supported value at this time.
- maxResults
-
- Type: int
The maximum number of items to return in one batch, between 10 and 100, inclusive.
- nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Result Syntax
[
'events' => [
[
'arn' => '<string>',
'availabilityZone' => '<string>',
'endTime' => <DateTime>,
'eventTypeCategory' => 'issue|accountNotification|scheduledChange',
'eventTypeCode' => '<string>',
'lastUpdatedTime' => <DateTime>,
'region' => '<string>',
'service' => '<string>',
'startTime' => <DateTime>,
'statusCode' => 'open|closed|upcoming',
],
// ...
],
'nextToken' => '<string>',
]
Result Details
Members
- events
-
- Type: Array of Event structures
The events that match the specified filter criteria.
- nextToken
-
- Type: string
If the results of a search are large, only a portion of the results are returned, and a
nextTokenpagination token is returned in the response. To retrieve the next batch of results, reissue the search request and include the returned token. When all results have been returned, the response does not contain a pagination token value.
Errors
-
InvalidPaginationToken:
The specified pagination token (
nextToken) is not valid. -
UnsupportedLocale:
The specified locale is not supported.
Shapes
AffectedEntity
Description
Information about an entity that is affected by a Health event.
Members
- awsAccountId
-
- Type: string
The 12-digit AWS account number that contains the affected entity.
- entityArn
-
- Type: string
The unique identifier for the entity. Format:
arn:aws:health:entity-region:aws-account:entity/entity-id. Example:arn:aws:health:us-east-1:111222333444:entity/AVh5GGT7ul1arKr1sE1K - entityUrl
-
- Type: string
- entityValue
-
- Type: string
The ID of the affected entity.
- eventArn
-
- Type: string
The unique identifier for the event. Format:
arn:aws:health:event-region::event/SERVICE/EVENT_TYPE_CODE/EVENT_TYPE_PLUS_ID. Example:Example: arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-DEF456 - lastUpdatedTime
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The most recent time that the entity was updated.
- statusCode
-
- Type: string
The most recent status of the entity affected by the event. The possible values are
IMPAIRED,UNIMPAIRED, andUNKNOWN. - tags
-
- Type: Associative array of custom strings keys (tagKey) to strings
A map of entity tags attached to the affected entity.
DateTimeRange
Description
A range of dates and times that is used by the EventFilter and EntityFilter objects. If from is set and to is set: match items where the timestamp (startTime, endTime, or lastUpdatedTime) is between from and to inclusive. If from is set and to is not set: match items where the timestamp value is equal to or after from. If from is not set and to is set: match items where the timestamp value is equal to or before to.
Members
EntityAggregate
Description
The number of entities that are affected by one or more events. Returned by the DescribeEntityAggregates operation.
Members
- count
-
- Type: int
The number entities that match the criteria for the specified events.
- eventArn
-
- Type: string
The unique identifier for the event. Format:
arn:aws:health:event-region::event/SERVICE/EVENT_TYPE_CODE/EVENT_TYPE_PLUS_ID. Example:Example: arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-DEF456
EntityFilter
Description
The values to use to filter results from the DescribeAffectedEntities operation.
Members
- entityArns
-
- Type: Array of strings
A list of entity ARNs (unique identifiers).
- entityValues
-
- Type: Array of strings
A list of IDs for affected entities.
- eventArns
-
- Required: Yes
- Type: Array of strings
A list of event ARNs (unique identifiers). For example:
"arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-CDE456", "arn:aws:health:us-west-1::event/EBS/AWS_EBS_LOST_VOLUME/AWS_EBS_LOST_VOLUME_CHI789_JKL101" - lastUpdatedTimes
-
- Type: Array of DateTimeRange structures
A list of the most recent dates and times that the entity was updated.
- statusCodes
-
- Type: Array of strings
A list of entity status codes (
IMPAIRED,UNIMPAIRED, orUNKNOWN). - tags
-
- Type: Array of stringss
A map of entity tags attached to the affected entity.
Event
Description
Summary information about an event, returned by the DescribeEvents operation. The DescribeEventDetails operation also returns this information, as well as the EventDescription and additional event metadata.
Members
- arn
-
- Type: string
The unique identifier for the event. Format:
arn:aws:health:event-region::event/SERVICE/EVENT_TYPE_CODE/EVENT_TYPE_PLUS_ID. Example:Example: arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-DEF456 - availabilityZone
-
- Type: string
The AWS Availability Zone of the event. For example, us-east-1a.
- endTime
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The date and time that the event ended.
- eventTypeCategory
-
- Type: string
The category of the event. Possible values are
issue,scheduledChange, andaccountNotification. - eventTypeCode
-
- Type: string
The unique identifier for the event type. The format is
AWS_SERVICE_DESCRIPTION; for example,AWS_EC2_SYSTEM_MAINTENANCE_EVENT. - lastUpdatedTime
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The most recent date and time that the event was updated.
- region
-
- Type: string
The AWS region name of the event.
- service
-
- Type: string
The AWS service that is affected by the event. For example,
EC2,RDS. - startTime
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The date and time that the event began.
- statusCode
-
- Type: string
The most recent status of the event. Possible values are
open,closed, andupcoming.
EventAggregate
Description
The number of events of each issue type. Returned by the DescribeEventAggregates operation.
Members
EventDescription
Description
The detailed description of the event. Included in the information returned by the DescribeEventDetails operation.
Members
EventDetails
Description
Detailed information about an event. A combination of an Event object, an EventDescription object, and additional metadata about the event. Returned by the DescribeEventDetails operation.
Members
- event
-
- Type: Event structure
Summary information about the event.
- eventDescription
-
- Type: EventDescription structure
The most recent description of the event.
- eventMetadata
-
- Type: Associative array of custom strings keys (metadataKey) to strings
Additional metadata about the event.
EventDetailsErrorItem
Description
Error information returned when a DescribeEventDetails operation cannot find a specified event.
Members
- errorMessage
-
- Type: string
A message that describes the error.
- errorName
-
- Type: string
The name of the error.
- eventArn
-
- Type: string
The unique identifier for the event. Format:
arn:aws:health:event-region::event/SERVICE/EVENT_TYPE_CODE/EVENT_TYPE_PLUS_ID. Example:Example: arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-DEF456
EventFilter
Description
The values to use to filter results from the DescribeEvents and DescribeEventAggregates operations.
Members
- availabilityZones
-
- Type: Array of strings
A list of AWS availability zones.
- endTimes
-
- Type: Array of DateTimeRange structures
A list of dates and times that the event ended.
- entityArns
-
- Type: Array of strings
A list of entity ARNs (unique identifiers).
- entityValues
-
- Type: Array of strings
A list of entity identifiers, such as EC2 instance IDs (
i-34ab692e) or EBS volumes (vol-426ab23e). - eventArns
-
- Type: Array of strings
A list of event ARNs (unique identifiers). For example:
"arn:aws:health:us-east-1::event/EC2/EC2_INSTANCE_RETIREMENT_SCHEDULED/EC2_INSTANCE_RETIREMENT_SCHEDULED_ABC123-CDE456", "arn:aws:health:us-west-1::event/EBS/AWS_EBS_LOST_VOLUME/AWS_EBS_LOST_VOLUME_CHI789_JKL101" - eventStatusCodes
-
- Type: Array of strings
A list of event status codes.
- eventTypeCategories
-
- Type: Array of strings
A list of event type category codes (
issue,scheduledChange, oraccountNotification). - eventTypeCodes
-
- Type: Array of strings
A list of unique identifiers for event types. For example,
"AWS_EC2_SYSTEM_MAINTENANCE_EVENT","AWS_RDS_MAINTENANCE_SCHEDULED" - lastUpdatedTimes
-
- Type: Array of DateTimeRange structures
A list of dates and times that the event was last updated.
- regions
-
- Type: Array of strings
A list of AWS regions.
- services
-
- Type: Array of strings
The AWS services associated with the event. For example,
EC2,RDS. - startTimes
-
- Type: Array of DateTimeRange structures
A list of dates and times that the event began.
- tags
-
- Type: Array of stringss
A map of entity tags attached to the affected entity.
EventType
Description
Metadata about a type of event that is reported by AWS Health. Data consists of the category (for example, issue), the service (for example, EC2), and the event type code (for example, AWS_EC2_SYSTEM_MAINTENANCE_EVENT).
Members
- category
-
- Type: string
A list of event type category codes (
issue,scheduledChange, oraccountNotification). - code
-
- Type: string
The unique identifier for the event type. The format is
AWS_SERVICE_DESCRIPTION; for example,AWS_EC2_SYSTEM_MAINTENANCE_EVENT. - service
-
- Type: string
The AWS service that is affected by the event. For example,
EC2,RDS.
