All Products
Search

This Product

    BSS OpenAPI:SubscribeBillToOSS

    Document Center

    BSS OpenAPI:SubscribeBillToOSS

    Last Updated:Jun 20, 2024

    Subscribes to the bills that are stored in Object Storage Service (OSS) buckets.

    Operation description

    Before you call this operation, take note of the following items:

    • You can subscribe to only one type of bill at a time.
    • The bills generated on the previous day are pushed on a daily basis the next day after you subscribe to the bills. The full-data bills for the previous month are pushed on the fourth day of each month. The monthly bills in the PDF format for the previous month are pushed on the fourth day of each month.
    • The daily bills may be delayed. The delayed bills are pushed the next day after they are generated. The delayed bills may include the bills that should have been pushed on the previous day. We recommend that you query the full-data bills for the previous month at the beginning of each month.
    • The bill subscriber must have the AliyunConsumeDump2OSSRole permission.
    • The SubscribeBillToOSS operation has the same functionality as the Save Expense Details to OSS Bucket feature in User Center.
    • To subscribe to the bills stored in an OSS bucket, make sure that the directory name specified for the OSS bucket conforms to the following naming rules:
      1. The directory name can contain only UTF-8 characters and cannot contain emoticons.
      1. Forward slashes (/) are used to separate paths and can be used to create subdirectories with ease. The directory name cannot start with a forward slash (/), a backslash (\), or consecutive forward slashes (/).
      1. The name of a subdirectory cannot be set to two consecutive periods (..).
      1. The directory name must be 1 to 254 characters in length.

    • File names:

      • BillingItemDetailForBillingPeriod (Detailed bills of billable items)

        • File name format for a daily push: UID_BillingItemDetail_YYYYMMDD. Example: 169**_BillingItemDetail_20190310.
        • File name format for a full-data push at the beginning of the next month: UID_BillingItemDetail_YYYYMM. Example: 169**_BillingItemDetail_201903.

      • InstanceDetailForBillingPeriod (Detailed bills of instances)

        • File name format for a daily push: UID_InstanceDetail_YYYYMMDD. Example: 169**_InstanceDetail_20190310.
        • File name format for a full-data push at the beginning of the next month: UID_InstanceDetail_YYYYMM. Example: 169**_InstanceDetail_201903.

      • InstanceDetailMonthly (Instance-based bills summarized by billing cycle)

        • File name format for a daily push: UID_InstanceDetailMonthly_YYYYMM. Example: 169**_InstanceDetailMonthly_201903. A bill of this type contains the full data generated from the beginning of the month to the current day, and is updated every day until the fourth day of the next month.

      • BillingItemDetailMonthly (Billable item-based bills summarized by billing cycle)

        • File name format for a daily push: UID_BillingItemDetailMonthly_YYYYMM. Example: 169**_BillingItemDetailMonthly_201903. A bill of this type contains the full data generated from the beginning of the month to the current day, and is updated every day until the fourth day of the next month.

      • SplitItemDetailDaily (Split bills summarized by day)

        • File name format for a daily push: UID_SplitItemDetailDaily_YYYYMM. Example: 169**_SplitItemDetailDaily_201903. A bill of this type contains the full data generated from the beginning of the month to the current day, and is updated every day until the fourth day of the next month.

      • MonthBill (Monthly bill in the PDF format)

        • File name format for a monthly push: UID_MonthBill_YYYYMM. Example: 169**_MonthBill_201903. The bill for the previous month is pushed on the fourth day of each month.

    • The bills of the MonthBill type are PDF files, whereas the bills of other types are CSV files. If the number of data rows in a bill exceeds a threshold, the bill is automatically split into multiple CSV files. Then, the multiple CSV files are automatically merged and compressed into a ZIP file that has the same name format as the original file.

    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
    bssapi:SubscribeBillToOSSWRITE
    • All Resources
      *
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    SubscribeBucketstringYes

    The OSS bucket that stores the bills to which you want to subscribe.

    		xxxxxx-bucket
    SubscribeTypestringNo

    The type of the bill to which you want to subscribe. Valid values:

    • BillingItemDetailForBillingPeriod: detailed bills of billable items
    • InstanceDetailForBillingPeriod: detailed bills of instances
    • BillingItemDetailMonthly: billable item-based bills summarized by billing cycle
    • InstanceDetailMonthly: instance-based bills summarized by billing cycle
    • SplitItemDetailDaily: split bills summarized by day
    • MonthBill: monthly bills in the PDF format. You can subscribe to the monthly PDF bills only of the master account.
    		BillingItemDetailForBillingPeriod
    MultAccountRelSubscribestringNo

    The type of the account whose bills are to be pushed if multi-tier accounts are involved. Valid values:

    • MA: the master account and a non-managed member account in Finance Cloud
    • ACP1: a member account of a virtual network operator (VNO)

    Default value: MA.

    		MA
    BucketOwnerIdlongNo

    The owner ID of the OSS bucket that stores the bills. This parameter is required if you are a bidder or reseller and want to push data to an OSS bucket of a member account. In this case, you must specify this account as the account used to call this operation and grant the AliyunConsumeDump2OSSRole permission to this account. If you are a regular user, you do not need to set this parameter. By default, your account is used to call this operation.

    		12341324
    BeginBillingCyclestringNo

    The initial billing cycle from which bills start to be pushed. After you subscribe to the bills, the system automatically pushes the data that is generated from the initial billing cycle to the current time. If the SubscribeType parameter is set to MonthBill, this parameter is invalid. Historical data is not pushed again. The data generated within the last year can be pushed.

    		2021-03
    BucketPathstringNo

    The path of the OSS bucket.

    		testpath
    RowLimitPerFileintegerNo

    The upper limit of the number of lines in a single file. When the bill file exceeds the upper limit, it will be split into multiple files and merged into a compressed package.

    		300000
    UsingSslstringNo

    Whether to protect network communications through the SSL (Secure Sockets Layer) encryption protocol. When this parameter is set to true, it means that SSL encryption is enabled to ensure the security and integrity of data transmission.

    		true

    Response parameters

    ParameterTypeDescriptionExample
    object
    Codestring

    The status code returned.

    		Success
    Messagestring

    The message returned.

    		Successful!
    RequestIdstring

    The ID of the request.

    		F61FCE4B-9B56-4FD9-A17E-******
    Successboolean

    Indicates whether the request is successful.

    		true

    Examples

    Sample success responses

    JSONformat

    {
  "Code": "Success",
  "Message": "Successful!",
  "RequestId": "F61FCE4B-9B56-4FD9-A17E-******",
  "Success": true
}

    Error codes

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

    Change history

    Change timeSummary of changesOperation
    2024-06-19The request parameters of the API has changedsee changesets
    Change itemChange content
    Input ParametersThe request parameters of the API has changed.
      Added Input Parameters: UsingSsl