Quota API

Note

In this section, the term "realm" means "organization". See Manage your organization.

Using the Quota API, you can construct a collection of rules to set limits, set alerts, and generally provide actions based on usage events in your organization. This service is used in conjunction with the Usage API, so that you can easily manage your service usage costs.

When a usage event occurs for your organization, all quota rules for your organization are evaluated, and if you reach the usage threshold for any rule, then the actions in the rule are used. The Quota API supports setting usage alerts and suspension based on billable services in your organization, project, or an app. When usage crosses the threshold defined in a rule, a violation is created.

You can use the Quota API to set quota rules at the organization level, project level, or app level through REST API access, to customize the Quota API for your unique circumstances.

Notes

The Quota API can be enabled for your organization by request. Please contact your account representative to request access.

Define quota rules for your organization

  • You can define quota rules at the organization level.
  • You must have createQuota permission.
  • You can define thresholds for a featureId, appId, or combination of featureId and appId.
  • The maximum number of rules allowed for an organization is 50.

A Rule has the following attributes:

  • QueryConditions: Defines the conditions for filtering the usage by featureId (featureHrn) or appId. Different services are measured in different units. As an example, data service transfer is measured in GB. The featureId is always mandatory in query conditions, when defining usage-based alerts.
  • UsageThresholdCondition: Defines the threshold conditions for billable usage. Two types of thresholds are available:
    • percentage: threshold value is determined as usageLimit*threshold/100. When the threshold type is a percentage, the maximum value is 100.
    • absolute: value from "threshold" field is used.
  • Actions are invoked when the rules meet query conditions and usageThresholdConditions. Available actions are:
    • alert: an email is sent to you about rule violations.
    • suspend: the service bundle access for that month is suspended, and you receive HTTP code 402 (Service quota exceeded).
  • TimeRange: Defines the date range for rule evaluation. Available values are:
    • daily: the rule is evaluated for all usage of an event date.
    • monthly: usage is evaluated for the calendar month.

Note

All Quota API requests require the Org ID (realmId) in the requests.

Quota API permissions

Once your organization has been granted access to the Quota API, your organization's users have the following permissions:

  • createQuota: All users within an enabled organization are granted createQuota permission. This permission enables you to add a quota rule, update a quota rule, and delete a quota rule.
  • deleteViolation: This permission enables you to delete quota violations from a organization. To get access to this permission, your org administrator must create a group, and then provide the groupId and your realmId to your account representative to set this up. Your org administrator can add and remove users from the group.

Create a new group

  1. To create a new group, start by entering the name of the group.

  2. Enter a description for the group.

Quota violations management

The group ID shown here lists the members of the group who can manage your quota violations.

Authorization

A Rule HRN is created for every quota rule. This is a system generated unique ID. When you create a rule, you are granted access to manage, read, and share the rule.

HRN format

hrn:here:quota::{customer organization}:{rule id}

Rule HRN example

hrn:here:quota::org123456789:CUSTOMER-QUOTA-dec030a3-738a-4925-99d6-0aec809d5f26

Quota rule evaluation

It takes a minimum of two hours to evaluate quota rules after invoking the Usage API.

Quota API Error Codes

  • E710001: Generic Exception.
  • E710002: {Resource} not found exception. Example Rule id not found.
  • E710003: UsageThresholdCondition object is required.
  • E710004: When threshold type is percentage:
    • threshold value cannot be more than 100.
    • threshold value must be greater than 0.
    • usageLimit must be greater than 0 if present.
    • thresholdCost must be greater than 0.
  • E710005: featureId condition is required when UsageThresholdCondition is present in the rule.
  • E710007: Maximum number of rules that can be created is 50.

Tutorials

For tutorials of how to use the Quota API, see Configure and use the Quota API rules.

results matching ""

    No results matching ""