Configuring a Bucket Inventory Rule (SDK forC)

If you have any questions during development, post them on the Issues page of GitHub.

Function

The bucket inventory function periodically generates lists of metadata information of objects in a bucket. Inventories help you better understand object statuses in the bucket. You can call this API to configure a bucket inventory rule.

Restrictions

To configure a bucket inventory rule, you must be the bucket owner or have the required permission (obs:bucket:PutBucketInventoryConfiguration granted using IAM or PutBucketInventoryConfiguration granted using a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Creating a Custom Bucket Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
A bucket can have a maximum of 100 inventory rules.
Each inventory rule ID must be unique within a bucket.
The destination bucket must already exist, and the source bucket owner must have the write permission on the destination bucket.

Method

void set_bucket_inventory(const obs_options *options,
    obs_inventory_configuration *inventory_config,
    obs_response_handler *handler, void *callback_data);

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
options	const obs_options*	Yes	Explanation: Context of the requested bucket. You can set the AK, SK, endpoint, bucket, timeout interval, and temporary credentials through obs_options. Restrictions: None Value range: None Default value: None
inventory_config	Table 2*	Yes	Explanation: Inventory configuration structure. Restrictions: None Value range: None Default value: None
handler	obs_response_handler *	Yes	Explanation: A callback structure where all members are pointers to callback functions, used to set the callback functions that handle response data. You can set a callback function to copy the response data from the server to callback_data (custom callback data). Restrictions: None Value range: None Default value: None
callback_data	void *	No	Explanation: Custom callback data. Restrictions: None Value range: None Default value: None

**Table 2** obs_inventory_configuration
Parameter	Type	Mandatory (Yes/No)	Description
id	char *	Yes	Explanation: Inventory rule ID, which uniquely identifies an inventory rule in a bucket. Restrictions: None Value range: The value can contain 1 to 64 characters. Default value: None
destination	Table 3*	Yes	Explanation: Destination bucket configuration, which specifies the location for storing inventory files. Restrictions: None Value range: None Default value: None
schedule	char *	Yes	Explanation: Generation frequency of inventories. Restrictions: None Value range: Daily Weekly Default value: None
format	char *	Yes	Explanation: Inventory file format. Restrictions: None Value range: CSV Default value: None
included_object_versions	char *	Yes	Explanation: Object versions included in the inventories. Restrictions: None Value range: All: All versions are included. Current: Only the current versions are included. Default value: None
filter	Table 4*	No	Explanation: Filter. Inventories are generated only for objects with the specified prefix. Restrictions: None Value range: None Default value: None
optional_fields	Table 5*	No	Explanation: Optional fields included in the inventories. Restrictions: None Value range: None Default value: None
is_enabled	bool	Yes	Explanation: Whether to enable the inventory rule. Restrictions: None Value range: true: enabled false: disabled Default value: false

**Table 3** obs_inventory_destination
Parameter	Type	Mandatory (Yes/No)	Description
bucket	char *	Yes	Explanation: Name of the bucket for storing inventory files. Restrictions: The destination bucket must already exist, and the source bucket owner must have the write permission on the destination bucket. Value range: None Default value: None
prefix	char *	No	Explanation: Prefix of the inventory files in the destination bucket. Restrictions: None Value range: None Default value: None

**Table 4** obs_inventory_filter
Parameter	Type	Mandatory (Yes/No)	Description
prefix	char *	No	Explanation: Object prefix. Inventories are generated only for objects with this prefix. Restrictions: None Value range: None Default value: None

**Table 5** obs_inventory_optional_fields
Parameter	Type	Mandatory (Yes/No)	Description
field_count	unsigned int	Yes	Explanation: Number of optional fields. Restrictions: None Value range: None Default value: None
fields	char **	Yes	Explanation: Array of optional fields. Restrictions: None Value range: Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, ReplicationStatus, and EncryptionStatus Default value: None

Sample Code

This example configures an inventory rule for a bucket.

#include "eSDKOBS.h"
#include <stdio.h>
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
int main()
{
    obs_initialize(OBS_INIT_ALL);
    obs_options options;
    init_obs_options(&options);
    // Enter the endpoint corresponding to the bucket for host_name. CN-Hong Kong is used here as an example. Replace it with the one currently in use.
    options.bucket_options.host_name = "obs.ap-southeast-1.myhuaweicloud.com";
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK and store them in the configuration file or environment variables.
    // In this example, the AK and SK are stored in environment variables for identity authentication. Before running the code in this example, configure local environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    options.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    options.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    options.bucket_options.bucket_name = "example-source-bucket";
    // Configure the destination bucket.
    obs_inventory_destination destination = {0};
    destination.bucket = "example-dest-bucket";
    destination.prefix = "inventory/";
    // Optional fields
    char *fields[] = {"Size", "LastModifiedDate", "StorageClass"};
    obs_inventory_optional_fields optional_fields = {0};
    optional_fields.field_count = 3;
    optional_fields.fields = fields;
    // Configure an inventory rule.
    obs_inventory_configuration inventory_config = {0};
    inventory_config.id = "inventory1";
    inventory_config.destination = &destination;
    inventory_config.schedule = "Daily";
    inventory_config.format = "CSV";
    inventory_config.included_object_versions = "Current";
    inventory_config.optional_fields = &optional_fields;
    inventory_config.is_enabled = true;
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_status ret_status = OBS_STATUS_BUTT;
    set_bucket_inventory(&options, &inventory_config, &response_handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("set bucket inventory successfully.\n");
    } else {
        printf("set bucket inventory failed(%s).\n", obs_get_status_name(ret_status));
    }
    obs_deinitialize();
}
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    (void)properties; (void)callback_data;
    return OBS_STATUS_OK;
}
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
    if (callback_data) { *(obs_status*)callback_data = status; }
    if (error && error->message) { printf("Error: %s\n", error->message); }
}