All Products
Search
Document Center

Dynamic Content Delivery Network:RefreshDcdnObjectCaches

Last Updated:Mar 01, 2024

Refreshes specified objects on points of presence (POPs). The objects can be included in the content of files or URLs. You can refresh multiple URLs in each request.

Operation description

  • DCDN supports POST requests in which parameters are sent as a form.
  • You can call the RefreshDcdnObjectCaches operation to refresh content and call the PreloadDcdnObjectCaches operation to prefetch content.
  • By default, each Alibaba Cloud account can refresh content from a maximum of 10,000 URLs and 100 directories per day, including subdirectories. If the daily peak bandwidth value exceeds 200 Mbit/s, you can submit a ticket to request a quota increase. DCDN evaluates your application based on your workloads.
  • You can specify up to 1,000 URLs or 100 directories that you want to refresh in each request.
  • You can refresh a maximum of 1,000 URLs per minute for each domain name.
  • You can call this operation up to 30 times per second per account.

Precautions

  • After a refresh task is submitted and completed, your resources that are stored on DCDN POPs are removed. When a POP receives a request to your resources, the request is redirected to the origin server to retrieve the resources. Then, the resources are returned to the client and cached on the POP. If you frequently run refresh tasks, more requests will be redirected to the origin server for resources, which result in high bandwidth costs and undue pressure on the origin server.
  • A refresh task takes effect 5 to 6 minutes after being submitted. This means that if the resource you want to refresh has a TTL of less than 5 minutes, you wait for it to expire instead of manually running a refresh task.
  • If you want to use RAM users to refresh or prefetch resources, you need to obtain the required permissions. For more information, see Authorize a RAM user to prefetch and refresh resources.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
dcdn:RefreshDcdnObjectCachesWRITE
  • domain
    acs:dcdn:*:{#accountId}:domain/{#domainName}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
ObjectPathstringYes

The path of the objects that you want to refresh. Separate multiple URLs with line feed characters (\n) or a pair of carriage return and line feed characters (\r\n).

example.com/example.txt
ObjectTypestringNo

The refresh type. Valid values:

  • File (default): refreshres resources based on URLs.
  • Directory: refreshes resources based on directories.
  • Regex: refreshes content based on regular expressions.
  • IgnoreParams: removes the question mark (?) and parameters after ? in a request URL and refreshes content. After you call this operation with the request URL submitted, the system compares the submitted URL with the URL of the cached resource without specific parameters. If the URLs match, the DCDN POPs refresh the cached resource.
Note
  • For more information about features of URL refresh and directory refresh, see Refresh and prefetch resources.
  • If you set ObjectType to Directory, the resources in the directory that you want to refresh are marked as expired. You cannot delete the directory. If clients request resources after the resources on POPs are marked as expired, DCDN checks whether the resources on your origin server are updated with a later version. If a later version exists, DCDN retrieves the resources of the later version and returns the resources to the clients. Otherwise, DCDN retrieves the 304 status code from the origin server.
  • File
    ForcebooleanNo

    Specifies whether to refresh resources in a directory if the resources are different from the resources in the same directory in the origin server. Default value: false.

    • true: refresh all resources in the directory.
    • false: refresh the changed resources in the directory.
    false

    Response parameters

    ParameterTypeDescriptionExample
    object
    RefreshTaskIdstring

    The ID of the refresh task. Multiple IDs are separated by commas (,).

    95248880
    RequestIdstring

    The ID of the request.

    E5BD4B50-7A02-493A-AE0B-97B9024B4135

    Examples

    Sample success responses

    JSONformat

    {
      "RefreshTaskId": "95248880",
      "RequestId": "E5BD4B50-7A02-493A-AE0B-97B9024B4135"
    }

    Error codes

    HTTP status codeError codeError messageDescription
    400SingleRequest.OverLimitA maximum of 1000 URLs are supported for each request.-
    400InvalidObjectType.MalformedThe specified ObjectType is invalid.The ObjectType parameter is set to an invalid value. Specify a valid value and try again.
    400InvalidObjectPath.MalformedThe specified ObjectPath is invalid.The ObjectPath parameter is set to an invalid value. Specify a valid value and try again.
    400QuotaExceeded.RefreshYour refresh attempts have exceeded the daily limit.The number of refresh tasks on the current day has reached the upper limit. You can call the refresh API operation to query the remaining number of refresh tasks that you want to run on the current day.
    400InvalidExtensiveDomain.ValueNotSupportedThe specified ExtensiveDomain is not supported.Wildcard domain names are not supported.
    400QuotaPerMinuteExceeded.RefreshYou tried to refresh too frequently; please try again later.Refresh requests are submitted too frequently. Try again later.
    400TooMany.RefreshThe refresh queue is full; please try again later.The maximum number of refresh requests for a domain name has been reached. Try again later.
    429TooManyRequestsToo many requests, please try again later-

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2023-10-17The Error code has changed. The request parameters of the API has changedsee changesets
    Change itemChange content
    Error CodesThe Error code has changed.
      delete Error Codes: 400
      delete Error Codes: 429
    Input ParametersThe request parameters of the API has changed.
      Added Input Parameters: Force
    2023-07-03The Error code has changedsee changesets
    Change itemChange content
    Error CodesThe Error code has changed.
      delete Error Codes: 400
      Added Error Codes: 429