get_top_path_statistics_by_traffic ¶

def get_top_path_statistics_by_traffic(
    self,
    web_acl_arn: "capo_wafv2.types.resource_arn.ResourceArn",
    scope: "capo_wafv2.types.scope.Scope",
    time_window: "capo_wafv2.types.time_window.TimeWindow",
    limit: "capo_wafv2.types.path_statistics_limit.PathStatisticsLimit",
    number_of_top_traffic_bots_per_path: "capo_wafv2.types.number_of_top_traffic_bots_per_path.NumberOfTopTrafficBotsPerPath",
    *,
    config_overrides: Optional[WAFV2ClientConfig] = None,
    uri_path_prefix: Optional[
        "capo_wafv2.types.uri_path_prefix_string.UriPathPrefixString"
    ] = None,
    bot_category: Optional["capo_wafv2.types.filter_string.FilterString"] = None,
    bot_organization: Optional[
        "capo_wafv2.types.filter_string.FilterString"
    ] = None,
    bot_name: Optional["capo_wafv2.types.filter_string.FilterString"] = None,
    next_marker: Optional["capo_wafv2.types.next_marker.NextMarker"] = None,
) -> "capo_wafv2.types.get_top_path_statistics_by_traffic_response.GetTopPathStatisticsByTrafficResponse":
    """<p>Retrieves aggregated statistics about the top URI paths accessed by bot traffic for a specified web ACL and time window. You can use this operation to analyze which paths on your web application receive the most bot traffic and identify the specific bots accessing those paths. The operation supports filtering by bot category, organization, or name, and allows you to drill down into specific path prefixes to view detailed URI-level statistics.</p>

    Args:
        web_acl_arn: <p>The Amazon Resource Name (ARN) of the web ACL for which you want to retrieve path statistics.</p>
        scope: <p>Specifies whether the web ACL is for an Amazon Web Services CloudFront distribution or for a regional application. A regional application can be an Application Load Balancer, an AppSync GraphQL API, an Amazon Cognito user pool, an Amazon Web Services App Runner service, or an Amazon Web Services Verified Access instance.</p>
        uri_path_prefix: <p>A URI path prefix to filter the results. When you specify this parameter, the operation returns statistics for individual URIs within the specified path prefix. For example, if you specify <code>/api</code>, the response includes statistics for paths like <code>/api/v1/users</code> and <code>/api/v2/orders</code>. If you don't specify this parameter, the operation returns top-level path statistics.</p>
        time_window: <p>The time window for which you want to retrieve path statistics. The time window must be within the data retention period for your web ACL.</p>
        bot_category: <p>Filters the results to include only traffic from bots in the specified category. For example, you can filter by <code>ai</code> to see only AI crawler traffic, or <code>search_engine</code> to see only search engine bot traffic. When you apply this filter, the <code>Source</code> field is populated in the response.</p>
        bot_organization: <p>Filters the results to include only traffic from bots belonging to the specified organization. For example, you can filter by <code>openai</code> or <code>google</code>. When you apply this filter, the <code>Source</code> field is populated in the response.</p>
        bot_name: <p>Filters the results to include only traffic from the specified bot. For example, you can filter by <code>gptbot</code> or <code>googlebot</code>. When you apply this filter, the <code>Source</code> field is populated in the response.</p>
        limit: <p>The maximum number of path statistics to return. Valid values are 1 to 100.</p>
        number_of_top_traffic_bots_per_path: <p>The maximum number of top bots to include in the statistics for each path. Valid values are 1 to 10.</p>
        next_marker: <p>When you request a list of objects with a <code>Limit</code> setting, if the number of objects that are still available for retrieval exceeds the limit, WAF returns a <code>NextMarker</code> value in the response. To retrieve the next batch of objects, provide the marker from the prior call in your next request.</p>

    Raises:
        capo_wafv2.errors.waf_feature_not_included_in_pricing_plan_exception.WAFFeatureNotIncludedInPricingPlanException: <p>The operation failed because the specified WAF feature isn't supported by the CloudFront pricing plan associated with the web ACL.</p>
        capo_wafv2.errors.waf_internal_error_exception.WAFInternalErrorException: <p>Your request is valid, but WAF couldn’t perform the operation because of a system problem. Retry your request. </p>
        capo_wafv2.errors.waf_invalid_operation_exception.WAFInvalidOperationException: <p>The operation isn't valid. </p>
        capo_wafv2.errors.waf_invalid_parameter_exception.WAFInvalidParameterException: <p>The operation failed because WAF didn't recognize a parameter in the request. For example: </p> <ul> <li> <p>You specified a parameter name or value that isn't valid.</p> </li> <li> <p>Your nested statement isn't valid. You might have tried to nest a statement that can’t be nested. </p> </li> <li> <p>You tried to update a <code>WebACL</code> with a <code>DefaultAction</code> that isn't among the types available at <a>DefaultAction</a>.</p> </li> <li> <p>Your request references an ARN that is malformed, or corresponds to a resource with which a web ACL can't be associated.</p> </li> </ul>
        capo_wafv2.errors.waf_nonexistent_item_exception.WAFNonexistentItemException: <p>WAF couldn’t perform the operation because your resource doesn't exist. If you've just created a resource that you're using in this operation, you might just need to wait a few minutes. It can take from a few seconds to a number of minutes for changes to propagate. </p>
        capo_wafv2.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    def _handler(
        req: "OperationRequest[capo_wafv2.types.get_top_path_statistics_by_traffic_request.GetTopPathStatisticsByTrafficRequest]",
    ) -> OperationResponse[
        "capo_wafv2.types.get_top_path_statistics_by_traffic_response.GetTopPathStatisticsByTrafficResponse"
    ]:
        import capo_wafv2._operations.awswaf_20190729.get_top_path_statistics_by_traffic

        output, http_response = (
            capo_wafv2._operations.awswaf_20190729.get_top_path_statistics_by_traffic.get_top_path_statistics_by_traffic(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("GetTopPathStatisticsByTraffic")
    )
    input_: capo_wafv2.types.get_top_path_statistics_by_traffic_request.GetTopPathStatisticsByTrafficRequest = {
        "web_acl_arn": web_acl_arn,
        "scope": scope,
        "time_window": time_window,
        "limit": limit,
        "number_of_top_traffic_bots_per_path": number_of_top_traffic_bots_per_path,
    }
    if uri_path_prefix is not None:
        input_["uri_path_prefix"] = uri_path_prefix
    if bot_category is not None:
        input_["bot_category"] = bot_category
    if bot_organization is not None:
        input_["bot_organization"] = bot_organization
    if bot_name is not None:
        input_["bot_name"] = bot_name
    if next_marker is not None:
        input_["next_marker"] = next_marker

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output