Quota service

Note

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

The quota service allows you to construct a collection of rules which provide limitations, set alerts, and generally provide actions based on usage events in your realm. This service is used in conjunction with the usage service, so that you can easily manage your service usage costs. You can think of the quota service as the configuration instance for your usage events.

When a usage event occurs for your realm, all quota rules for your realm are evaluated, and if the usage threshold is met for any rule, then actions defined in the rule are taken. The quota service supports setting usage alerts and suspension based on cloud service in a realm, project, or an app. When usage crosses the threshold defined in the rule, violations are created.

The quota service allows you to set quota rules at the realm level, project level, or app level through REST API access, and provides a method for you to customize the quota API for your unique circumstances.

Notes

Usage alerts and suspension are not available for data service storage usage.

The quota service is available by contacting your account representative.

Usage arrival can take up to 2 hours for Location Services and up to 48 hours for billable cloud services, which means quota rule conditions can take this long to enact.

Define quota rules for your realm

• You can define quota rules at the realm level
• You must have createQuota permission
• Quota rule definition allows configuring usage thresholds for a featureId, appId, or a combination of featureId and appId
• The maximum rules allowed in a realm are 50

The Rule object has the following attributes:

• QueryConditions: Defines the conditions for filtering the usage by featureId(featureHrn) or appId. Different services (features) are measured in different Unit of measures. As an example, data service transfer is measured in GB. 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:
• 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

Notes

This service is dependent on Usage API v2.

Usage arrival can take up to 2 hours for Location Services and up to 48 hours for billable cloud services, which means quota rule conditions can take this long to enact.

All the quota service APIs require the Org ID (Realm id).

Quota service permissions

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

Create a new group

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

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. When you create a rule, you are granted access to manage, read, and share the rule.

HRN format

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


Rule HRN

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


Quota rule evaluation

It takes a minimum of 2 hours to evaluate quota rules, after the HERE service usage.

Error Codes

• E710001: Generic Exception
• 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 service, see Tutorials: Quota service.