Manage static website hosting

Object Storage Service (OSS) allows you to host static websites on buckets and configure mirroring-based back-to-origin rules. When static website hosting is enabled, visitors to the bucket are automatically redirected to the specified default homepage or default 404 page. Mirroring-based back-to-origin rules enable seamless data migration to OSS.

Usage notes

The sample code in this topic uses the region ID cn-hangzhou of the China (Hangzhou) region. By default, the public endpoint is used to access resources in a bucket. If you want to access resources in the bucket by using other Alibaba Cloud services in the same region in which the bucket is located, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and Endpoints.
To configure static website hosting or mirroring-based back-to-origin, you must have the oss:PutBucketWebsite permission. To query static website hosting configurations or mirroring-based back-to-origin rules, you must have the oss:GetBucketWebsite permission. To delete static website hosting configurations or mirroring-based back-to-origin rules, you must have the oss:DeleteBucketWebsite permission. For more information, see Grant a custom policy.

Static websites consist entirely of static content, including client-side scripts such as JavaScript. You can host a static website in an OSS bucket and access it through the bucket's domain name.

Configure static website hosting

The following sample code shows how to configure static website hosting:

<?php

// Introduce autoload files to load dependent libraries.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Specify descriptions for command line parameters.
$optsdesc = [
    "region" => ['help' => The region in which the bucket is located.', 'required' => True], // (Required) Specify the region in which the bucket is located.
    "endpoint" => ['help' => The domain names that other services can use to access OSS.', 'required' => False], // (Optional) Specify the endpoint that can be used by other services to access OSS.
    "bucket" => ['help' => The name of the bucket, 'required' => True], // (Required) Specify the name of the bucket.
];

// Generate a long options list to parse the command line parameters.
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) to the end of each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line parameters.
$options = getopt("", $longopts); 

// Check whether the required parameters are configured.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Indicate that the required parameters are not configured.
        exit(1); 
    }
}

// Obtain the values of the command line parameters.
$region = $options["region"]; // The region in which the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Use environment variables to load the AccessKey ID and AccessKey secret.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();

// Specify the credential provider.
$cfg->setCredentialsProvider($credentialsProvider);

// Specify the region.
$cfg->setRegion($region);

// Specify the endpoint if an endpoint is provided.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// Create an OSSClient instance.
$client = new Oss\Client($cfg);

// Create a PutBucketWebsiteRequest object to configure static website hosting for the bucket.
$request = new Oss\Models\PutBucketWebsiteRequest(bucket: $bucket,
    websiteConfiguration: new Oss\Models\WebsiteConfiguration(
        indexDocument: new Oss\Models\IndexDocument(
            suffix: 'index.html', // Specify the name of the file that is used as the default homepage.
            supportSubDir: true, // Enable the subdirectory homepage feature for the bucket.
            type: 0 // The type of the index page.
        ),
        errorDocument: new Oss\Models\ErrorDocument(
            key: 'error.html', // The name of the file that is used as the default 404 page.
            httpStatus: 404 // The HTTP status code returned on the default 404 page.
        )
    )
);

// Use the putBucketWebsite method to configure static website hosting for the bucket.
$result = $client->putBucketWebsite($request);

// Display the returned result.
printf(
    'status code:' . $result->statusCode . PHP_EOL . // The returned HTTP status code.
    'request id:' . $result->requestId // The request ID of the request, which is the unique identifier of the request.
);

Query the static website hosting configurations of a bucket

The following sample code shows how to query the static website hosting configurations of a bucket:

<?php

// Introduce autoload files to load dependent libraries.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Specify descriptions for command line parameters.
$optsdesc = [
    "region" => ['help' => The region in which the bucket is located.', 'required' => True], // (Required) Specify the region in which the bucket is located.
    "endpoint" => ['help' => The domain names that other services can use to access OSS.', 'required' => False], // (Optional) Specify the endpoint that can be used by other services to access OSS.
    "bucket" => ['help' => The name of the bucket, 'required' => True], // (Required) Specify the name of the bucket.
];

// Generate a long options list to parse the command line parameters.
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) to the end of each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line parameters.
$options = getopt("", $longopts); 

// Check whether the required parameters are configured.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Indicate that the required parameters are not configured.
        exit(1); 
    }
}

// Obtain the values of the command line parameters.
$region = $options["region"]; // The region in which the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Use environment variables to load the AccessKey ID and AccessKey secret.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();

// Specify the credential provider.
$cfg->setCredentialsProvider($credentialsProvider);

// Specify the region.
$cfg->setRegion($region);

// Specify the endpoint if an endpoint is provided.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// Create an OSSClient instance.
$client = new Oss\Client($cfg);

// Create a GetBucketWebsiteRequest object to query the static website hosting configurations of the bucket.
$request = new Oss\Models\GetBucketWebsiteRequest(bucket: $bucket);

// Use the getBucketWebsite method to query the static website hosting configurations of the bucket.
$result = $client->getBucketWebsite($request);

// Display the returned result.
printf(
    'status code:' . $result->statusCode . PHP_EOL . // The returned HTTP status code.
    'request id:' . $result->requestId . PHP_EOL . // The request ID of the request, which is the unique identifier of the request.
    'website config:' . var_export($result->websiteConfiguration, true) . PHP_EOL // The static website hosting configurations.
);

Delete the static website hosting configurations of a bucket

The following sample code shows how to delete the static website hosting configurations of a bucket:

<?php

// Introduce autoload files to load dependent libraries.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Specify descriptions for command line parameters.
$optsdesc = [
    "region" => ['help' => The region in which the bucket is located.', 'required' => True], // (Required) Specify the region in which the bucket is located.
    "endpoint" => ['help' => The domain names that other services can use to access OSS.', 'required' => False], // (Optional) Specify the endpoint that can be used by other services to access OSS.
    "bucket" => ['help' => The name of the bucket, 'required' => True], // (Required) Specify the name of the bucket.
];

// Generate a long options list to parse the command line parameters.
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) to the end of each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line parameters.
$options = getopt("", $longopts); 

// Check whether the required parameters are configured.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Indicate that the required parameters are not configured.
        exit(1); 
    }
}

// Obtain the values of the command line parameters.
$region = $options["region"]; // The region in which the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Use environment variables to load the AccessKey ID and AccessKey secret.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();

// Specify the credential provider.
$cfg->setCredentialsProvider($credentialsProvider);

// Specify the region.
$cfg->setRegion($region);

// Specify the endpoint if an endpoint is provided.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// Create an OSSClient instance.
$client = new Oss\Client($cfg);

// Create a DeleteBucketWebsiteRequest object to delete the static website hosting configurations of the bucket.
$request = new Oss\Models\DeleteBucketWebsiteRequest(bucket: $bucket);

// Use the deleteBucketWebsite method to delete the static website hosting configurations of the bucket.
$result = $client->deleteBucketWebsite($request);

// Display the returned result.
printf(
    'status code:' . $result->statusCode . PHP_EOL . // The returned HTTP status code.
    'request id:' . $result->requestId // The request ID of the request, which is the unique identifier of the request.
);

Manage mirroring-based back-to-origin

Mirroring-based back-to-origin enables seamless data migration to OSS from a self-managed origin or another cloud service without service interruptions. During migration, any data not yet migrated to OSS is transparently retrieved from the origin, ensuring business continuity.

Configure mirroring-based back-to-origin rules for a bucket

If a requester accesses an object that does not exist in the specified bucket, you can specify the URL of the object in the origin and back-to-origin conditions to retrieve the object from the origin. For example, if a bucket named examplebucket is located in the China (Hangzhou) region and a requester accesses a nonexistent object in the examplefolder directory of the root directory of the bucket, the requester is redirected to www.example.com to access the object stored in the examplefolder directory of the origin.

The following sample code shows how to configure mirroring-based back-to-origin rules in this scenario:

<?php

// Introduce autoload files to load dependent libraries.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Specify descriptions for command line parameters.
$optsdesc = [
    "region" => ['help' => The region in which the bucket is located.', 'required' => True], // (Required) Specify the region in which the bucket is located.
    "endpoint" => ['help' => The domain names that other services can use to access OSS.', 'required' => False], // (Optional) Specify the endpoint that can be used by other services to access OSS.
    "bucket" => ['help' => The name of the bucket, 'required' => True], // (Required) Specify the name of the bucket.
];

// Generate a long options list to parse the command line parameters.
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) to the end of each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line parameters.
$options = getopt("", $longopts); 

// Check whether the required parameters are configured.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Indicate that the required parameters are not configured.
        exit(1); 
    }
}

// Obtain the values of the command line parameters.
$region = $options["region"]; // The region in which the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Use environment variables to load the AccessKey ID and AccessKey secret.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();

// Specify the credential provider.
$cfg->setCredentialsProvider($credentialsProvider);

// Specify the region.
$cfg->setRegion($region);

// Specify the endpoint if an endpoint is provided.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// Create an OSSClient instance.
$client = new Oss\Client($cfg);

// Specify mirroring-based back-to-origin rules.
$ruleOk = new Oss\Models\RoutingRule(
    ruleNumber: 1, // The rule number.
    condition: new Oss\Models\RoutingRuleCondition(
        keyPrefixEquals: 'myobject', // Specify the prefix contained in the names of the objects that you want to retrieve.
        httpErrorCodeReturnedEquals: 404 // Set the back-to-origin condition to HTTP status code 404.
    ),
    redirect: new Oss\Models\RoutingRuleRedirect(
        redirectType: 'Mirror', // Set the redirection type to Mirror.
        mirrorURL: 'http://www.test.com/', // Specify the origin URL.
        mirrorHeaders: new Oss\Models\MirrorHeaders(
            passAll: false, // Specify whether to transmit all HTTP headers.
            passs: ['myheader-key1', 'myheader-key2'], // Specify the HTTP headers that can be transmitted.
            removes: ['myheader-key3', 'myheader-key4'], // Specify the HTTP headers that cannot be transmitted.
            sets: [
                new Oss\Models\MirrorHeadersSet(
                    key: 'myheader-key5', // Specify the names of the specified HTTP headers.
                    value: 'myheader-value' // Specify the values of the specified HTTP headers.
                ),
            ]
        )
    )
);

// Create a PutBucketWebsite request.
$request = new Oss\Models\PutBucketWebsiteRequest(
    bucket: $bucketName, // The name of the bucket.
    websiteConfiguration: new Oss\Models\WebsiteConfiguration(
        indexDocument: new Oss\Models\IndexDocument(
            suffix: 'index.html', // The default homepage for the mirroring-based back-to-origin request.
            supportSubDir: true,
            type: 0
        ),
        errorDocument: new Oss\Models\ErrorDocument(
            key: 'error.html', // The default 404 page for the mirroring-based back-to-origin request.
            httpStatus: 404
        ),
        routingRules: new Oss\Models\RoutingRules(
            routingRules: [$ruleOk] // The mirroring-based back-to-origin rules.
        )
    )
);

// Execute the PutBucketWebsite request.
$result = $client->putBucketWebsite($request);

// Display the returned result.
printf(
    'status code:' . $result->statusCode . PHP_EOL . // The returned HTTP status code.
    'request id:' . $result->requestId . PHP_EOL . // The request ID of the request, which is the unique identifier of the request.
    'website config:' . var_export($result->websiteConfiguration, true) . PHP_EOL // The static website hosting configurations.
);

Query the mirroring-based back-to-origin rules of a bucket

The following sample code shows how to query the mirroring-based back-to-origin rules of a bucket:

<?php

// Introduce autoload files to load dependent libraries.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Specify descriptions for command line parameters.
$optsdesc = [
    "region" => ['help' => The region in which the bucket is located.', 'required' => True], // (Required) Specify the region in which the bucket is located.
    "endpoint" => ['help' => The domain names that other services can use to access OSS.', 'required' => False], // (Optional) Specify the endpoint that can be used by other services to access OSS.
    "bucket" => ['help' => The name of the bucket, 'required' => True], // (Required) Specify the name of the bucket.
];

// Generate a long options list to parse the command line parameters.
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) to the end of each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line parameters.
$options = getopt("", $longopts); 

// Check whether the required parameters are configured.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Indicate that the required parameters are not configured.
        exit(1); 
    }
}

// Obtain the values of the command line parameters.
$region = $options["region"]; // The region in which the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Use environment variables to load the AccessKey ID and AccessKey secret.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();

// Specify the credential provider.
$cfg->setCredentialsProvider($credentialsProvider);

// Specify the region.
$cfg->setRegion($region);

// Specify the endpoint if an endpoint is provided.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// Create an OSSClient instance.
$client = new Oss\Client($cfg);

// Create a GetBucketWebsite request.
$request = new Oss\Models\GetBucketWebsiteRequest(
    bucket: $bucketName, // The name of the bucket.
);

// Execute the GetBucketWebsite request.
$result = $client->getBucketWebsite($request);

// Display the returned result.
printf(
    'status code:' . $result->statusCode . PHP_EOL . // The returned HTTP status code.
    'request id:' . $result->requestId . PHP_EOL . // The request ID of the request, which is the unique identifier of the request.
    'website config:' . var_export($result->websiteConfiguration, true) . PHP_EOL // The static website hosting configurations.
);

Delete the mirroring-based back-to-origin rules of a bucket

The following sample code shows how to delete the mirroring-based back-to-origin rules of a bucket:

<?php

// Introduce autoload files to load dependent libraries.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Specify descriptions for command line parameters.
$optsdesc = [
    "region" => ['help' => The region in which the bucket is located.', 'required' => True], // (Required) Specify the region in which the bucket is located.
    "endpoint" => ['help' => The domain names that other services can use to access OSS.', 'required' => False], // (Optional) Specify the endpoint that can be used by other services to access OSS.
    "bucket" => ['help' => The name of the bucket, 'required' => True], // (Required) Specify the name of the bucket.
];

// Generate a long options list to parse the command line parameters.
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) to the end of each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line parameters.
$options = getopt("", $longopts); 

// Check whether the required parameters are configured.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Indicate that the required parameters are not configured.
        exit(1); 
    }
}

// Obtain the values of the command line parameters.
$region = $options["region"]; // The region in which the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Use environment variables to load the AccessKey ID and AccessKey secret.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();

// Specify the credential provider.
$cfg->setCredentialsProvider($credentialsProvider);

// Specify the region.
$cfg->setRegion($region);

// Specify the endpoint if an endpoint is provided.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// Create an OSSClient instance.
$client = new Oss\Client($cfg);


// Create a DeleteBucketWebsite request.
$request = new Oss\Models\DeleteBucketWebsiteRequest(
    bucket: $bucketName, // The name of the bucket.
);

// Use the deleteBucketWebsite method to delete the static website hosting configurations of the bucket.
$result = $client->deleteBucketWebsite($request);

// Display the returned result.
printf(
    'status code:' . $result->statusCode . PHP_EOL . // The returned HTTP status code.
    'request id:' . $result->requestId // The request ID of the request, which is the unique identifier of the request.
);

References

For complete sample code for managing static website hosting and mirroring-based back-to-origin, visit put_bucket_website, get_bucket_website, and delete_bucket_website.
For more information about the API operation that you can call to configure static website hosting or mirroring-based back-to-origin, see PutBucketWebsite.
For more information about the API operation that you can call to query static website hosting configurations or mirroring-based back-to-origin rules, see GetBucketWebsite.
For more information about the API operation that you can call to delete static website hosting configurations or mirroring-based back-to-origin rules, see DeleteBucketWebsite.