Connect / Client / search_metrics

search_metrics¶

Connect.Client.search_metrics(**kwargs)¶

Searches for metrics in the specified Connect Customer instance using search criteria and optional tag-based filters. Use pagination to ensure that the operation returns quickly and successfully.

Request Syntax

response = client.search_metrics(
    InstanceId='string',
    NextToken='string',
    MaxResults=123,
    SearchFilter={
        'TagFilter': {
            'OrConditions': [
                [
                    {
                        'TagKey': 'string',
                        'TagValue': 'string'
                    },
                ],
            ],
            'AndConditions': [
                {
                    'TagKey': 'string',
                    'TagValue': 'string'
                },
            ],
            'TagCondition': {
                'TagKey': 'string',
                'TagValue': 'string'
            }
        }
    },
    SearchCriteria={
        'OrConditions': [
            {'... recursive ...'},
        ],
        'AndConditions': [
            {'... recursive ...'},
        ],
        'StringCondition': {
            'FieldName': 'string',
            'Value': 'string',
            'ComparisonType': 'STARTS_WITH'|'CONTAINS'|'EXACT'
        },
        'BooleanCondition': {
            'FieldName': 'string',
            'ComparisonType': 'IS_TRUE'|'IS_FALSE'
        }
    }
)

Parameters:

InstanceId (string) –
[REQUIRED]

The identifier of the Connect Customer instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
NextToken (string) – The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.
MaxResults (integer) – The maximum number of results to return per page.
SearchFilter (dict) –
Filters to be applied to search results.
- TagFilter (dict) –
  
  An object that can be used to specify tag conditions inside the SearchFilter. This accepts an OR of AND (List of List) input where:
  - The top level list specifies conditions that need to be applied with OR operator.
  - The inner list specifies conditions that need to be applied with AND operator.
  - OrConditions (list) –
    
    A list of conditions which would be applied together with an OR condition.
    - (list) –
      - (dict) –
        
        A leaf node condition which can be used to specify a tag condition, for example, HAVE BPO = 123.
        
        TagKey (string) –
        
        The tag key in the tag condition.
        
        TagValue (string) –
        
        The tag value in the tag condition.
  - AndConditions (list) –
    
    A list of conditions which would be applied together with an AND condition.
    - (dict) –
      
      A leaf node condition which can be used to specify a tag condition, for example, HAVE BPO = 123.
      - TagKey (string) –
        
        The tag key in the tag condition.
      - TagValue (string) –
        
        The tag value in the tag condition.
  - TagCondition (dict) –
    
    A leaf node condition which can be used to specify a tag condition.
    - TagKey (string) –
      
      The tag key in the tag condition.
    - TagValue (string) –
      
      The tag value in the tag condition.
SearchCriteria (dict) –
The search criteria to filter the metrics.
- OrConditions (list) –
  
  A list of conditions to be met, where at least one condition must be satisfied.
  - (dict) –
    
    Defines the search criteria for filtering metrics.
- AndConditions (list) –
  
  A list of conditions that must all be satisfied.
  - (dict) –
    
    Defines the search criteria for filtering metrics.
- StringCondition (dict) –
  
  A leaf node condition which can be used to specify a string condition.
  - FieldName (string) –
    
    The name of the field in the string condition.
  - Value (string) –
    
    The value of the string.
  - ComparisonType (string) –
    
    The type of comparison to be made when evaluating the string condition.
- BooleanCondition (dict) –
  
  A boolean search condition for Search APIs.
  - FieldName (string) –
    
    A name of the property to be searched.
  - ComparisonType (string) –
    
    Boolean property comparison type.

Return type:

dict

Returns:

Response Syntax

{
    'Metrics': [
        {
            'Arn': 'string',
            'Id': 'string',
            'Name': 'string',
            'Description': 'string',
            'MetricCalculation': {
                'CalculationComponents': [
                    {
                        'Alias': 'string',
                        'MetricName': 'string',
                        'MetricId': 'string',
                        'MetricFilters': [
                            {
                                'MetricFilterKey': 'string',
                                'Negate': True|False,
                                'NumberCondition': {
                                    'Comparison': 'LESSER'|'LESSER_OR_EQUAL'|'GREATER'|'GREATER_OR_EQUAL',
                                    'Values': [
                                        123.0,
                                    ]
                                },
                                'StringCondition': {
                                    'Comparison': 'MATCHES_ANY'|'MATCHES_NONE',
                                    'Values': [
                                        'string',
                                    ]
                                },
                                'BooleanCondition': {
                                    'Comparison': 'IS_TRUE'|'IS_FALSE'
                                }
                            },
                        ]
                    },
                ],
                'Calculation': 'string'
            },
            'CreationMethod': 'SERVICE_LEVEL_BUILDER'|'METRIC_BUILDER',
            'Status': 'PUBLISHED'|'SAVED',
            'Type': 'AWS_MANAGED'|'CUSTOMER_MANAGED',
            'Unit': 'INTEGER'|'DOUBLE'|'PERCENT'|'SECONDS',
            'PositiveTrendIndicator': 'POSITIVE'|'NEGATIVE'|'NEUTRAL',
            'Groupings': [
                'string',
            ],
            'Filters': [
                {
                    'Id': 'string',
                    'Type': 'METRIC_LEVEL'|'RESOURCE_LEVEL'
                },
            ],
            'EffectiveTime': datetime(2015, 1, 1),
            'RefreshRate': 123,
            'Category': 'string',
            'SupportedStats': [
                'string',
            ],
            'DefaultStat': 'string',
            'SupportsPreaggregateCalculation': True|False,
            'SupportsCustomCalculation': True|False,
            'PrimaryEventSource': 'string',
            'PrimaryEventSourceEffectiveTimestampType': 'string',
            'CreatedTime': datetime(2015, 1, 1),
            'CreatedUser': {
                'ConnectUserArn': 'string',
                'AWSIdentityArn': 'string'
            },
            'LastModifiedRegion': 'string',
            'LastModifiedTime': datetime(2015, 1, 1),
            'LastModifiedUser': {
                'ConnectUserArn': 'string',
                'AWSIdentityArn': 'string'
            },
            'Tags': {
                'string': 'string'
            }
        },
    ],
    'NextToken': 'string',
    'ApproximateTotalCount': 123
}

Response Structure

(dict) –
- Metrics (list) –
  
  The metrics that matched the search criteria.
  - (dict) –
    
    Contains the full definition of a metric, including its calculation, unit, status, and trend indicator.
    - Arn (string) –
      
      The Amazon Resource Name (ARN) of the metric. May be qualified with $SAVED or $LATEST.
    - Id (string) –
      
      The identifier of the metric.
    - Name (string) –
      
      The name of the metric.
    - Description (string) –
      
      The description of the metric.
    - MetricCalculation (dict) –
      
      The calculation definition for the metric.
      - CalculationComponents (list) –
        
        The list of component metrics referenced in the calculation formula. Each component has an alias used in the formula expression.
        
        (dict) –
        
        Represents a component metric referenced in a custom metric calculation formula.
        
        Alias (string) –
        
        The alias used to reference this component in the calculation expression.
        
        MetricName (string) –
        
        The name of an AWS-managed metric used in this calculation component (for example, CONTACTS_HANDLED). Mutually exclusive with MetricId.
        
        MetricId (string) –
        
        The ARN of an AWS-managed metric used in this calculation component. Mutually exclusive with MetricName.
        
        MetricFilters (list) –
        
        The filters applied to the calculation component.
        
        (dict) –
        
        A filter condition applied to a metric component in a calculation. Filters restrict the data included in the metric computation.
        
        MetricFilterKey (string) –
        
        The key identifying the field to filter on.
        
        Negate (boolean) –
        
        Specifies whether the filter condition is negated. When set to true, the filter excludes matching data instead of including it.
        
        NumberCondition (dict) –
        
        A numeric comparison condition.
        
        Comparison (string) –
        
        The comparison operator. Valid values: LESSER (less than) | LESSER_OR_EQUAL (less than or equal to) | GREATER (greater than) | GREATER_OR_EQUAL (greater than or equal to).
        
        Values (list) –
        
        The numeric values to compare against.
        
        (float) –
        
        StringCondition (dict) –
        
        A string comparison condition.
        
        Comparison (string) –
        
        The comparison operator. Valid values: MATCHES_ANY (matches any of the specified values) | MATCHES_NONE (matches none of the specified values).
        
        Values (list) –
        
        The string values to compare against.
        
        (string) –
        
        BooleanCondition (dict) –
        
        A boolean comparison condition.
        
        Comparison (string) –
        
        The comparison operator. Valid values: IS_TRUE (matches when the field is true) | IS_FALSE (matches when the field is false).
      - Calculation (string) –
        
        The formula expression that defines how the metric is calculated. Uses component aliases (for example, 100 * SUM(M1) / SUM(M2)).
    - CreationMethod (string) –
      
      The method used to create the metric. Valid values: SERVICE_LEVEL_BUILDER (created with the guided service-level experience) | METRIC_BUILDER (created with the free-form metric builder).
    - Status (string) –
      
      The publish status of the metric. Valid values: PUBLISHED | SAVED.
    - Type (string) –
      
      The type of the metric. Valid values: AWS_MANAGED | CUSTOMER_MANAGED.
    - Unit (string) –
      
      The display unit for the metric’s data.
    - PositiveTrendIndicator (string) –
      
      How an increase in the metric value should be interpreted. Valid values: POSITIVE, NEUTRAL, NEGATIVE.
    - Groupings (list) –
      
      The groupings available for this metric.
      - (string) –
    - Filters (list) –
      
      The filters applied to the metric.
      - (dict) –
        
        A filter that is available for use with the metric. Part of an AvailableFilterList that describes the filters that are available for use with the metric.
        
        Id (string) –
        
        The identifier of the filter.
        
        Type (string) –
        
        The type of the filter. Valid values: METRIC_LEVEL | RESOURCE_LEVEL.
    - EffectiveTime (datetime) –
      
      The earliest time that can be queried for this metric.
    - RefreshRate (integer) –
      
      The minimum interval, in seconds, between data refreshes for this metric.
    - Category (string) –
      
      The category of the metric.
    - SupportedStats (list) –
      
      The stat aggregations available for this metric.
      - (string) –
    - DefaultStat (string) –
      
      The default stat aggregation for the metric.
    - SupportsPreaggregateCalculation (boolean) –
      
      Specifies whether the metric can be used inside aggregating statistical functions (SUM, AVG, etc.) in custom metric calculations.
    - SupportsCustomCalculation (boolean) –
      
      Specifies whether the metric can be used as a component of custom metrics.
    - PrimaryEventSource (string) –
      
      The primary event source for the metric data.
    - PrimaryEventSourceEffectiveTimestampType (string) –
      
      The timestamp type that determines where the metric appears on a time series.
    - CreatedTime (datetime) –
      
      The timestamp of when the metric was created.
    - CreatedUser (dict) –
      
      The user that created the metric. The creator for metrics created through the CreateMetric API will be Amazon Connect API.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: ConnectUserArn, AWSIdentityArn. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - ConnectUserArn (string) –
        
        An agent ARN representing a connect user.
      - AWSIdentityArn (string) –
        
        STS or IAM ARN representing the identity of API Caller. SDK users cannot populate this and this value is calculated automatically if ConnectUserArn is not provided.
    - LastModifiedRegion (string) –
      
      The region where the metric was last modified.
    - LastModifiedTime (datetime) –
      
      The timestamp of when the metric was last modified.
    - LastModifiedUser (dict) –
      
      The user that last modified the metric. For modifications made through the API, this will be Amazon Connect API.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: ConnectUserArn, AWSIdentityArn. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - ConnectUserArn (string) –
        
        An agent ARN representing a connect user.
      - AWSIdentityArn (string) –
        
        STS or IAM ARN representing the identity of API Caller. SDK users cannot populate this and this value is calculated automatically if ConnectUserArn is not provided.
    - Tags (dict) –
      
      The tags used to organize, track, or control access for this resource. For example, { “Tags”: {“key1”:”value1”, “key2”:”value2”} }.
      - (string) –
        
        (string) –
- NextToken (string) –
  
  If there are additional results, this is the token for the next set of results.
- ApproximateTotalCount (integer) –
  
  The approximate total number of metrics that matched your search criteria.

Exceptions

Connect.Client.exceptions.InvalidRequestException
Connect.Client.exceptions.InvalidParameterException
Connect.Client.exceptions.ResourceNotFoundException
Connect.Client.exceptions.ThrottlingException
Connect.Client.exceptions.InternalServiceException
Connect.Client.exceptions.AccessDeniedException