Setting a Container-Specific Policy Using the REST API

Not Oracle Cloud at Customer This topic does not apply to Oracle Cloud at Customer.

You can specify a different replication policy for each container other than the account-level policy. The container-level policy overrides the account-level policy. This enables you to control, at a more granular level, what data gets replicated to a geographical distant data center (DC).

Any user with the Service Administrator role can perform this task.

Note:

  • You cannot set replication policies for archive containers.
  • You can set the container-level replication policy when you create a container or when the container is empty.

Setting a Container-Specific Policy in a Data Center Within the Same Region Using the REST API

You can set your container’s source DC and georeplication DC to be a subset of that of the service instance. For example, if the primary DC of your service instance is us2 and the georeplication DCs are us6 and uscom-central-1, then the primary DC of your container can be us6, us2, or uscom-central-1. One or both of the remaining DCs can be selected as the replication DC of the container. Specify your container’s primary DC URL and replication DC URLs in the sourceRegion and targetRegions parameters respectively in the request body JSON file.

Write requests to a container for which you've set a replication policy must be sent to the DC-specific REST endpoint URL, and not to the global namespace URL.

DC-specific REST endpoint URLs are in the format:

https://dataCenterCode.storage.oraclecloud.com/v1/Storage-identityDomainID

Example: https://us2.storage.oraclecloud.com/Storage-myDomain

Setting a Container-Specific Policy in a Different Region Using the REST API

You can specify a replication policy for your container by selecting a data center outside the region where the primary DC and georeplication DC of your service instance are located. For example, if the primary DC and georeplication DC of your service instance are us2 and us6 in the US region, then you can select a data center, say em2 that’s located in a non-US region to replicate your container. Specify the external container to which the objects from your container must be replicated by specifying the external container’s URL in the externalTargetRegions parameter of the request body JSON file. You can specify multiple external replication DCs for your container.

When your container is the destination for the replication of objects from an external container, specify the external container’s URL in the externalSourceRegions parameter of the request body JSON file. Your container can be the destination for replication of objects from multiple source containers.

Note:

While setting the container’s replication policy in a different region, first set the replication policy of the target region with the externalSourceRegions parameter, and next set the replication of the source region with the externalTargetRegions parameter.

Important:

To set the container’s replication policy in a different region, ensure that the REST Endpoint URLs specified in the request body JSON file are in the GUID format. For example: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer.

Do not use the friendly name format. For example: https://acme.storage.oraclecloud.com/v1/Storage-acme/myContainer. The friendly name REST Endpoint URLs may change and lead to invalid replication policy.

Creating the Request Body JSON File

Create a request body JSON file using the following template and store it on your host:

{
  "sourceRegion": {
    "name": "primary_DC_code",
    "url": "primary_DC_url"},
  "targetRegions": [{
    "name": "replication_DC_code",
    "url": "replication_DC_url"}],
  "externalSourceRegions": [{
    "name": "external",
    "url": "external_source_url"}],
  "externalTargetRegions": [{
    "name": "external",
    "url": "external_target_url"}]
}
  • primary_DC_code is the data center code of the primary DC of your container.

  • primary_DC_url is the URL of your container located in the primary DC of your container. This is an optional parameter.

  • replication_DC_code is the data center code of the replication DC of your container.

  • replication_DC_url is the URL of the replication of your container located in the replication DC of your container. This is an optional parameter.

  • external_source_url is the URL of the container in an external region from which the objects would be replicated into your container.

  • external_target_url is the URL of the container in an external region into which the objects in your container must be replicated.

Note:

The parameters primary_DC_url and replication_DC_url are optional. Providing the data center code is sufficient for the normal working of the command.
  • Example request body JSON file for your container myContainer in the following scenario:
    • Your service instance has us2 primary DC.

    • Your service instance has us6 and uscom-central-1 replication DCs.

    • Primary DC for your container is us6.

    • Replication DCs for your container areus2 and uscom-central-1 within the same region.

    Note that the examples demonstrate the use of GUID-based URLs to set the source and target regions. If the GUID-based URL for the container is https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer, then <fooN> is storage-7b16fede61e1417ab83eb52e06f0e365 and <barN> is 7b16fede61e1417ab83eb52e06f0e365.
    {
      "sourceRegion": {
        "name": "us6",
        "url": "https://<foo1>.storage.oraclecloud.com/v1/Storage-<bar1>/myContainer"},
      "targetRegions": [{
        "name": "us2",
        "url": "https://<foo2>.storage.oraclecloud.com/v1/Storage-<bar2>/myContainer"}, {
        "name": "uscom-central-1",
        "url": "https://<foo3>.storage.oraclecloud.com/v1/Storage-<bar3>/myContainer"}],
      "externalSourceRegions": [],
      "externalTargetRegions": []
    }
  • Example request body JSON file for your container mySecondContainer in the following scenario:
    • Your service instance has us2 primary DC and us6 replication DC.

    • Primary DC for your container is us2.

    • Replication DC for your container is us6 within the same region.

    • Your container is the destination for replication from a container externalSourceContainer1 and externalSourceContainer2 that reside in different regions.

    • The objects in your container are replicated to the container externalTargetContainer in a data center of a different region.

    Note that the examples demonstrate the use of GUID-based URLs to set the source and target regions. If the GUID-based URL for the container is https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer, then <fooN> is storage-7b16fede61e1417ab83eb52e06f0e365 and <barN> is 7b16fede61e1417ab83eb52e06f0e365.
    {
      "sourceRegion": {
        "name": "us2",
        "url": "https://<foo4>.storage.oraclecloud.com/v1/Storage-<bar4>/mySecondContainer"},
      "targetRegions": [{
        "name": "us6",
        "url": "https://<foo5>.storage.oraclecloud.com/v1/Storage-<bar5>/mySecondContainer"}],
      "externalSourceRegions": [{
        "name": "external",
        "url": "https://<foo6>.storage.oraclecloud.com/v1/Storage-<bar6>/externalSourceContainer1"}, {
        "name": "external",
        "url": "https://<foo7>.storage.oraclecloud.com/v1/Storage-<bar7>/externalSourceContainer2"}],
      "externalTargetRegions": [{
        "name": "external",
        "url": "https://<foo8>.storage.oraclecloud.com/v1/Storage-<bar8>/externalTargetContainer"}]
    }

cURL Command Syntax to Specify the Replication Policy for a Container

  • To specify a replication policy for an empty container:
    curl -v -X POST \
         -H "X-Auth-Token: token" \
         -H "Content-Type: application/json" \
         -d "@file" \
         accountURL/containerName?repPolicy
    
  • To specify a replication policy while creating a container:
    curl -v -X PUT \
         -H "X-Auth-Token: token" \
         -d "@file" \
         accountURL/containerName?repPolicy
    
  • To read a container’s replication policy:
    curl -v -X GET \
         -H "X-Auth-Token: token" \
         accountURL/containerName?repPolicy
    

Note:

When you send a REST API request to Oracle Cloud Infrastructure Object Storage Classic, all non-ASCII characters in container names, object names and metadata values must be URL-encoded. For example, my container should be encoded as my%20container, where %20 is the HTML encoding for the space character. Similarly, my Über Container should be encoded as my%20%C3%9Cber%20Container, where %20 represents the space character and %C3%9C is the Ü character.

HTTP Response Codes

  • Success:
    • When updating a container with the replication policy: 204 No Content
    • When creating a container and specifying the replication policy: 201 Created
    • When reading a container’s replication policy: 200 OK
  • Failure: See Error Code Reference for Object Storage Classic

cURL Command Examples

  1. This command sets the replication policy for the container FirstContainer:
    curl -v -X POST \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         -H "Content-Type: application/json" \
         -d "@requestbody.json" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer?repPolicy
    

    The following is an example of the output of this command:

    > POST /v1/Storage-acme/FirstContainer?repPolicy HTTP/1.1
    > User-Agent: curl/7.49.1
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > Content-Type: application/json
    > Content-Length: 489
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    >
    * upload completely sent off: 489 out of 489 bytes
    < HTTP/1.1 204 No Content
    < Date: Fri, 10 Nov 2017 06:32:55 GMT
    < Content-Type: text/html;charset=UTF-8
    < X-Trans-Id: txe8869b3edea348e5b49eb-0054f99743
    
  2. This command specifies the replication policy while creating the container SecondContainer:
    curl -v -X PUT \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         -d "@requestbody.json" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/SecondContainer?repPolicy
    

    The following is an example of the output of this command:

    > PUT /v1/Storage-acme/SecondContainer?repPolicy HTTP/1.1
    > User-Agent: curl/7.49.1
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    >
    < HTTP/1.1 201 Created
    < Date: Thu, 09 Nov 2017 10:03:18 GMT
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: txe8869b3edea348e5b49eb-0054f99678
    < X-Last-Modified-Timestamp: 1510221797.90473
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
    
  3. This command displays the replication policy of the container FirstContainer:
    curl -v -X GET \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer?repPolicy
    

    The following is an example of the output of this command:

    > GET /v1/Storage-acme/FirstContainer?repPolicy HTTP/1.1
    > User-Agent: curl/7.49.1
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    >
    < HTTP/1.1 200 OK
    < < Date: Fri, 10 Nov 2017 06:17:44 GMT
    < Content-Type: application/json;charset=UTF-8
    < X-Trans-Id: txe8869b3edea348e5b49eb-0054f99838
    {
      "mode": "ACTIVE_PASSIVE",
      "sourceRegion": {
        "name": "us2",
        "url": "https://<foo9>.storage.oraclecloud.com/v1/Storage-<bar9>/FirstContainer"
      },
      "targetRegions": [{
        "name": "us6",
        "url": "https://<foo10>.storage.oraclecloud.com/v1/Storage-<bar10>/FirstContainer"
      }],
      "externalSourceRegions": [{
        "name": "external",
        "url": "https://<foo11>.storage.oraclecloud.com/v1/Storage-<bar11>/ExternalSourceContainer"
      }],
      "externalTargetRegions": [{
        "name": "external",
        "url": "https://<foo12>.storage.oraclecloud.com/v1/Storage-<bar12>/ExternalTargetContainer"
      }]
    * STATE: PERFORM => DONE handle 0x600057870; line 1955 (connection #0)
    * multi_done
    * Connection #0 to host left intact
    }

    Note that the example output displays the GUID-based URLs that are used to set the source and target regions. If the GUID-based URL for the container is https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer, then <fooN> is storage-7b16fede61e1417ab83eb52e06f0e365 and <barN> is 7b16fede61e1417ab83eb52e06f0e365.