WAFV2 / Client / get_sampled_requests

get_sampled_requests#

WAFV2.Client.get_sampled_requests(**kwargs)#

Gets detailed information about a specified number of requests–a sample–that WAF randomly selects from among the first 5,000 requests that your Amazon Web Services resource received during a time range that you choose. You can specify a sample size of up to 500 requests, and you can specify any time range in the previous three hours.

GetSampledRequests returns a time range, which is usually the time range that you specified. However, if your resource (such as a CloudFront distribution) received 5,000 requests before the specified time range elapsed, GetSampledRequests returns an updated time range. This new time range indicates the actual period during which WAF selected the requests in the sample.

See also: AWS API Documentation

Request Syntax

response = client.get_sampled_requests(
    WebAclArn='string',
    RuleMetricName='string',
    Scope='CLOUDFRONT'|'REGIONAL',
    TimeWindow={
        'StartTime': datetime(2015, 1, 1),
        'EndTime': datetime(2015, 1, 1)
    },
    MaxItems=123
)

Parameters:

WebAclArn (string) –
[REQUIRED]

The Amazon resource name (ARN) of the WebACL for which you want a sample of requests.
RuleMetricName (string) –
[REQUIRED]

The metric name assigned to the Rule or RuleGroup dimension for which you want a sample of requests.
Scope (string) –
[REQUIRED]

Specifies whether this is for an Amazon CloudFront distribution or for a regional application. A regional application can be an Application Load Balancer (ALB), an Amazon API Gateway REST API, an AppSync GraphQL API, an Amazon Cognito user pool, or an App Runner service.

To work with CloudFront, you must also specify the Region US East (N. Virginia) as follows:
- CLI - Specify the Region when you use the CloudFront scope: --scope=CLOUDFRONT --region=us-east-1.
- API and SDKs - For all calls, use the Region endpoint us-east-1.
TimeWindow (dict) –
[REQUIRED]

The start date and time and the end date and time of the range for which you want GetSampledRequests to return a sample of requests. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator, Z. For example, "2016-09-27T14:50Z". You can specify any time range in the previous three hours. If you specify a start time that’s earlier than three hours ago, WAF sets it to three hours ago.
- StartTime (datetime) – [REQUIRED]
  
  The beginning of the time range from which you want GetSampledRequests to return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator, Z. For example, "2016-09-27T14:50Z". You can specify any time range in the previous three hours.
- EndTime (datetime) – [REQUIRED]
  
  The end of the time range from which you want GetSampledRequests to return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator, Z. For example, "2016-09-27T14:50Z". You can specify any time range in the previous three hours.
MaxItems (integer) –
[REQUIRED]

The number of requests that you want WAF to return from among the first 5,000 requests that your Amazon Web Services resource received during the time range. If your resource received fewer requests than the value of MaxItems, GetSampledRequests returns information about all of them.

Return type:

dict

Returns:

Response Syntax

{
    'SampledRequests': [
        {
            'Request': {
                'ClientIP': 'string',
                'Country': 'string',
                'URI': 'string',
                'Method': 'string',
                'HTTPVersion': 'string',
                'Headers': [
                    {
                        'Name': 'string',
                        'Value': 'string'
                    },
                ]
            },
            'Weight': 123,
            'Timestamp': datetime(2015, 1, 1),
            'Action': 'string',
            'RuleNameWithinRuleGroup': 'string',
            'RequestHeadersInserted': [
                {
                    'Name': 'string',
                    'Value': 'string'
                },
            ],
            'ResponseCodeSent': 123,
            'Labels': [
                {
                    'Name': 'string'
                },
            ],
            'CaptchaResponse': {
                'ResponseCode': 123,
                'SolveTimestamp': 123,
                'FailureReason': 'TOKEN_MISSING'|'TOKEN_EXPIRED'|'TOKEN_INVALID'|'TOKEN_DOMAIN_MISMATCH'
            },
            'ChallengeResponse': {
                'ResponseCode': 123,
                'SolveTimestamp': 123,
                'FailureReason': 'TOKEN_MISSING'|'TOKEN_EXPIRED'|'TOKEN_INVALID'|'TOKEN_DOMAIN_MISMATCH'
            },
            'OverriddenAction': 'string'
        },
    ],
    'PopulationSize': 123,
    'TimeWindow': {
        'StartTime': datetime(2015, 1, 1),
        'EndTime': datetime(2015, 1, 1)
    }
}

Response Structure

(dict) –
- SampledRequests (list) –
  
  A complex type that contains detailed information about each of the requests in the sample.
  - (dict) –
    
    Represents a single sampled web request. The response from GetSampledRequests includes a SampledHTTPRequests complex type that appears as SampledRequests in the response syntax. SampledHTTPRequests contains an array of SampledHTTPRequest objects.
    - Request (dict) –
      
      A complex type that contains detailed information about the request.
      - ClientIP (string) –
        
        The IP address that the request originated from. If the web ACL is associated with a CloudFront distribution, this is the value of one of the following fields in CloudFront access logs:
        
        c-ip, if the viewer did not use an HTTP proxy or a load balancer to send the request
        
        x-forwarded-for, if the viewer did use an HTTP proxy or a load balancer to send the request
      - Country (string) –
        
        The two-letter country code for the country that the request originated from. For a current list of country codes, see the Wikipedia entry ISO 3166-1 alpha-2.
      - URI (string) –
        
        The URI path of the request, which identifies the resource, for example, /images/daily-ad.jpg.
      - Method (string) –
        
        The HTTP method specified in the sampled web request.
      - HTTPVersion (string) –
        
        The HTTP version specified in the sampled web request, for example, HTTP/1.1.
      - Headers (list) –
        
        A complex type that contains the name and value for each header in the sampled web request.
        
        (dict) –
        
        Part of the response from GetSampledRequests. This is a complex type that appears as Headers in the response syntax. HTTPHeader contains the names and values of all of the headers that appear in one of the web requests.
        
        Name (string) –
        
        The name of the HTTP header.
        
        Value (string) –
        
        The value of the HTTP header.
    - Weight (integer) –
      
      A value that indicates how one result in the response relates proportionally to other results in the response. For example, a result that has a weight of 2 represents roughly twice as many web requests as a result that has a weight of 1.
    - Timestamp (datetime) –
      
      The time at which WAF received the request from your Amazon Web Services resource, in Unix time format (in seconds).
    - Action (string) –
      
      The action that WAF applied to the request.
    - RuleNameWithinRuleGroup (string) –
      
      The name of the Rule that the request matched. For managed rule groups, the format for this name is <vendor name>#<managed rule group name>#<rule name>. For your own rule groups, the format for this name is <rule group name>#<rule name>. If the rule is not in a rule group, this field is absent.
    - RequestHeadersInserted (list) –
      
      Custom request headers inserted by WAF into the request, according to the custom request configuration for the matching rule action.
      - (dict) –
        
        Part of the response from GetSampledRequests. This is a complex type that appears as Headers in the response syntax. HTTPHeader contains the names and values of all of the headers that appear in one of the web requests.
        
        Name (string) –
        
        The name of the HTTP header.
        
        Value (string) –
        
        The value of the HTTP header.
    - ResponseCodeSent (integer) –
      
      The response code that was sent for the request.
    - Labels (list) –
      
      Labels applied to the web request by matching rules. WAF applies fully qualified labels to matching web requests. A fully qualified label is the concatenation of a label namespace and a rule label. The rule’s rule group or web ACL defines the label namespace.
      
      For example, awswaf:111122223333:myRuleGroup:testRules:testNS1:testNS2:labelNameA or awswaf:managed:aws:managed-rule-set:header:encoding:utf8.
      - (dict) –
        
        A single label container. This is used as an element of a label array in multiple contexts, for example, in RuleLabels inside a Rule and in Labels inside a SampledHTTPRequest.
        
        Name (string) –
        
        The label string.
    - CaptchaResponse (dict) –
      
      The CAPTCHA response for the request.
      - ResponseCode (integer) –
        
        The HTTP response code indicating the status of the CAPTCHA token in the web request. If the token is missing, invalid, or expired, this code is 405 Method Not Allowed.
      - SolveTimestamp (integer) –
        
        The time that the CAPTCHA was last solved for the supplied token.
      - FailureReason (string) –
        
        The reason for failure, populated when the evaluation of the token fails.
    - ChallengeResponse (dict) –
      
      The Challenge response for the request.
      - ResponseCode (integer) –
        
        The HTTP response code indicating the status of the challenge token in the web request. If the token is missing, invalid, or expired, this code is 202 Request Accepted.
      - SolveTimestamp (integer) –
        
        The time that the challenge was last solved for the supplied token.
      - FailureReason (string) –
        
        The reason for failure, populated when the evaluation of the token fails.
    - OverriddenAction (string) –
      
      Used only for rule group rules that have a rule action override in place in the web ACL. This is the action that the rule group rule is configured for, and not the action that was applied to the request. The action that WAF applied is the Action value.
- PopulationSize (integer) –
  
  The total number of requests from which GetSampledRequests got a sample of MaxItems requests. If PopulationSize is less than MaxItems, the sample includes every request that your Amazon Web Services resource received during the specified time range.
- TimeWindow (dict) –
  
  Usually, TimeWindow is the time range that you specified in the GetSampledRequests request. However, if your Amazon Web Services resource received more than 5,000 requests during the time range that you specified in the request, GetSampledRequests returns the time range for the first 5,000 requests. Times are in Coordinated Universal Time (UTC) format.
  - StartTime (datetime) –
    
    The beginning of the time range from which you want GetSampledRequests to return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator, Z. For example, "2016-09-27T14:50Z". You can specify any time range in the previous three hours.
  - EndTime (datetime) –
    
    The end of the time range from which you want GetSampledRequests to return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator, Z. For example, "2016-09-27T14:50Z". You can specify any time range in the previous three hours.

Exceptions

WAFV2.Client.exceptions.WAFNonexistentItemException
WAFV2.Client.exceptions.WAFInternalErrorException
WAFV2.Client.exceptions.WAFInvalidParameterException