Getting bucket information

You can get information about buckets that are associated with an object storage account. Bucket information is required to register an object storage account with IBM Spectrum Protect Plus.

Method and URI

To get bucket information, use a POST method with a URI:

POST    https://{hostname|IPv4}/api/cloud

Parameters

Parameter 1: action

Request information about object storage buckets that are associated with the cloud storage accounts.

  • Value: getBuckets

  • Type: System string. Required. Available in the web user interface.

Data

Data 1: provider

The type of cloud storage provider. Use one of the following system values:

Provider

Value

Amazon S3

aws

IBM Cloud Object Storage

cos

Microsoft Azure Blob Storage

azure

S3 compatible object storage

generic

  • Type: System string. Required. Available in the web user interface.

Data 2: accesskey

An access key that was registered with IBM Spectrum Protect Plus. For details, see Keys and Certificates. To get the bucket information about a new object storage account, enter an empty JSON object ({}).

  • Example value:

{
    "href": "https://10.0.0.100/api/identity/key/1003"
}
  • Type: JSON object.

Data 2.1: accesskey > href

The URL of the access key. Typically, it has the following syntax:

https://{hostname|IPv4}/api/identity/key/{identityKeyId}
  • Type: String.

Tip

To get an {identityKeyId} value based on its name, follow the instructions in Getting an {identityKeyId}.

Data 3: properties

The properties of the object storage account.

  • Type: Array. Required. Available in the web user interface.

Data 3.1: properties > region

The region of the Amazon S3 storage account. Use one of the following system values:

Amazon S3 region

Value

US East (Virginia)

us-east-1

US East (Ohio)

us-east-2

US West (N. California)

us-west-1

US West (Oregon)

us-west-2

Asia Pacific (Tokyo)

ap-northeast-1

Asia Pacific (Seoul)

ap-northeast-2

Asia Pacific (Osaka-Local)

ap-northeast-3

Asia Pacific (Mumbai)

ap-south-1

Asia Pacific (Singapore)

ap-southeast-1

Asia Pacific (Sydney)

ap-southeast-2

Canada (Central)

ca-central-1

China (Beijing)

cn-north-1

China (Ningxia)

cn-northwest-1

EU (Frankfurt)

eu-central-1

EU (Ireland)

eu-west-1

EU (London)

eu-west-2

EU (Paris)

eu-west-3

EU (Stockholm)

eu-north-1

South America (São Paulo)

sa-east-1

  • Type: System string.

Data 3.2: properties > endpoint

The endpoint URL of the account managed by IBM Cloud Object Storage, S3 compatible object storage, and Microsoft Azure Blob Storage. For Microsoft Azure Blob Storage accounts, use one of the following endpoint URLs:

Microsoft Azure endpoint

Value

Microsoft Azure Global

https://core.windows.net:443

Microsoft Azure Germany

https://core.cloudapi.de:443

Microsoft Azure China 21 Vianet

https://core.chinacloudapi.cn:443

Microsoft Azure USA Government

https://core.usgovcloudapi.net:443

  • Type: String.

Data 3.3: properties > accessKey

The access key of the account managed by Amazon S3, IBM Cloud Object Storage, and S3 compatible object storage; or the storage account name of the Microsoft Azure Blob Storage account.

  • Example value: QAH6fG85SkPmyEfqn4yy

  • Type: String

Data 3.4: properties > secretKey

The secret access key for an Amazon S3 or S3 compatible object storage account; the secret key for an IBM Cloud Object Storage account; or the storage account shared key, account key, or access key for a Microsoft Azure Blob Storage account.

Example 1: Get bucket information about Amazon S3 account

Assume that you want to get information about buckets that are associated with the following Amazon S3 account:

  • Region: US West (N. California)

  • Access key: Q3Z3MCDF7WJVG7KREFWFG

  • Secret access key: rNzSHk2gBfjf9cECGp+cjrhEdhsZmxwHnRckk8BP

A Python snippet that is similar to the following example can be used to get information about the buckets that are associated with this Amazon S3 account:

_params = {"action": "getBuckets"}

_data = f'''{{
    "provider":    "aws",
    "properties":  {{
        "region":    "us-west-1",
        "accessKey": "Q3Z3MCDF7WJVG7KREFWFG",
        "secretKey": "rNzSHk2gBfjf9cECGp+cjrhEdhsZmxwHnRckk8BP"
    }}
}}'''

requests.post('https://' + spp_ipv4 + '/api/cloud',
    headers={...}, params=_params, data=_data, verify=...)

The request prompts a response that is structured as shown, with the HTTP status of 200 (OK). Every bucket object has the name and ID that are the same string.

{
    "total": 3,
    "buckets": [
        {
            "links": {},
            "id": "bluemachines-sales",
            "name": "bluemachines-sales",
            "protectionConfiguration": null,
            "haslifecycleRules": false,
            "hasBucketArchiveLifecycleRules": false,
            "resourceType": "bucket"
        },
        {...}, {...}
    ]
}
_images/reference_objectstorage_bucket01aws.png

Figure 40 The same action can be taken in the IBM Spectrum Protect Plus web user interface: In the Object Storage pane, click Add Object Storage. In the Object Storage Registration section, set Provider to “Amazon S3”, configure the required settings, and click Get Buckets.

Example 2: Get bucket information by using an existing access key

As mentioned, you can also reuse an existing access key instead of entering the access key and the secret key of the object storage account. Assume that you want to get information about buckets that are associated with the following Amazon S3 account and the access key that was registered with IBM Spectrum Protect Plus:

  • Region: US West (N. California)

  • Access key: “BlueMachines Amazon S3 California Key” ({identityKeyId} 1003)

A Python snippet that is similar to the following example can be used to get information about the buckets that are associated with this Amazon S3 account:

_params = {"action": "getBuckets"}

_data = f'''{{
    "provider":    "aws",
    "accesskey":   {{
        "href": "https://10.0.0.100/api/identity/key/1003"
    }}
    "properties":  {{
        "region":    "us-west-1",
    }}
}}'''

requests.post('https://' + spp_ipv4 + '/api/cloud',
    headers={...}, params=_params, data=_data, verify=...)

The request prompts a response with the HTTP status of 200 (OK). The response body is similar to the JSON object, as shown in Example 1: Get bucket information about Amazon S3 account.

{
    "total": 3,
    "buckets": [
        {
            "links": {},
            "id": "bluemachines-sales",
            "name": "bluemachines-sales",
            "protectionConfiguration": null,
            "haslifecycleRules": false,
            "hasBucketArchiveLifecycleRules": false,
            "resourceType": "bucket"
        },
        {...}, {...}
    ]
}
_images/reference_objectstorage_bucket02accesskey.png

Figure 41 You can also use an existing access key that was registered with IBM Spectrum Protect Plus.

Example 3: Get bucket information for an IBM Cloud Object Storage account

Assume that you want to get information about buckets that are associated with the following IBM Cloud Object Storage account:

  • Endpoint: https://ibmcos.bluemachines.com.invalid

  • Access key: QAH6fG85SkPmyEfqn4yy

  • Secret access key: ddUTAun9DBHuehkC2TLwkfH7WyEzQ8PaCxJ4xNYnr

A Python snippet that is similar to the following example can be used to get information about the buckets that are associated with this IBM Cloud Object Storage account:

_params = {"action": "getBuckets"}

_data = f'''{{
    "provider":    "cos",
    "properties":  {{
        "endpoint":  "https://ibmcos.bluemachines.com.invalid",
        "accessKey": "QAH6fG85SkPmyEfqn4yy",
        "secretKey": "ddUTAun9DBHuehkC2TLwkfH7WyEzQ8PaCxJ4xNYnrr"
    }}
}}'''

requests.post('https://' + spp_ipv4 + '/api/cloud',
    headers={...}, params=_params, data=_data, verify=...)

The request prompts a response with the HTTP status of 200 (OK). The response body is similar to the JSON object, as shown in Example 1: Get bucket information about Amazon S3 account.

_images/reference_objectstorage_bucket02cos.png

Figure 42 In the Object Storage Registration section, set Provider to “IBM Cloud Object Storage”, configure the required settings, and click Get Buckets.

Example 4: Get bucket information for a Microsoft Azure Blob Storage account

Assume that you want to get information about buckets that are associated with the following Microsoft Azure Blob Storage account:

  • Endpoint: Microsoft Azure Global

  • Storage Account Name: bluemachines-azure

  • Storage Account Shared Key: VUAZ87JC6MKT7D5FXW+YZ24DDXXHWP3P9HZT +2J5V88LN8KWAZH4NW3R4PE495FHWKVZPTPSGR4QEUJ5TWH4DL==

A Python snippet that is similar to the following example can be used to get information about the buckets that are associated with this Microsoft Azure Blob Storage account:

_params = {"action": "getBuckets"}

_data = f'''{{
    "provider":    "azure",
    "properties":  {{
        "endpoint":  "https://core.windows.net:443",
        "accessKey": "azure-bluemachines",
        "secretKey": "VUAZ87JC6MKT7D5FXW+YZ24DDXXHWP3P9HZT+2J5V88LN8KWAZH4NW3R4P
E495FHWKVZPTPSGR4QEUJ5TWH4DL=="
    }}
}}'''

requests.post('https://' + spp_ipv4 + '/api/cloud',
    headers={...}, params=_params, data=_data, verify=...)

The request prompts a response with the HTTP status of 200 (OK). The response body is similar to the JSON object, as shown in Example 1: Get bucket information about Amazon S3 account.

_images/reference_objectstorage_bucket03azure.png

Figure 43 To obtain bucket information from the IBM Spectrum Protect Plus web user interface, in the navigation pane, click System Configuration > Backup Storage > Object Storage. Then, in the Object Storage Registration section, from the Provider list, select Microsoft Azure Blob Storage, configure the required settings, and click Get Buckets.

Example 5: Get bucket information about an S3 compatible object storage account

Assume that you want to get information about buckets that are associated with the following S3 compatible object storage account:

  • Endpoint: https://s3.volvox.com.invalid

  • Access key: PJNG6J5FHENHWZ66K77X

  • Secret access key: CFBF8QcKtMSMYTE++mX3pUWSwmchNBgg5afbnw5T

A Python snippet that is similar to the following example can be used to get information about the buckets that are associated with this the S3 compatible object storage account:

_params = {"action": "getBuckets"}

_data = f'''{{
    "provider":    "generic",
    "properties":  {{
        "endpoint":  "https://s3.volvox.com.invalid",
        "accessKey": "PJNG6J5FHENHWZ66K77X",
        "secretKey": "CFBF8QcKtMSMYTE++mX3pUWSwmchNBgg5afbnw5T"
    }}
}}'''

requests.post('https://' + spp_ipv4 + '/api/cloud',
    headers={...}, params=_params, data=_data, verify=...)

The request prompts a response with the HTTP status of 200 (OK). The response body is similar to the JSON object, as shown in Example 1: Get bucket information about Amazon S3 account.

_images/reference_objectstorage_bucket04generic.png

Figure 44 In the Object Storage Registration section, set Provider to “Microsoft Azure Blob Storage”, configure the required settings, and click Get Buckets.