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 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 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, follow the instructions in 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 the name of the identity key, 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 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, or 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, or 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 for an 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).

Tip

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 38 To get information about buckets that are associated with an Amazon S3 account, in the navigation pane, click System Configuration > Backup Storage > Object Storage. Then, in the Object Storage pane, click Add Object Storage. In the Object Storage Registration section, from the Provider list, select 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 for an 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 39 To obtain an existing access key from the IBM Spectrum Protect Plus user interface, in the navigation pane, click System Configuration > Backup Storage > Object Storage. Then, review the object storage registration information.

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: ddUTAun9DBHuehkC2TLwkfH7WyEzQ8PaCxJ4xNYn

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": "ddUTAun9DBHuehkC2TLwkfH7WyEzQ8PaCxJ4xNYn"
    }}
}}'''

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 for an Amazon S3 account.

_images/reference_objectstorage_bucket02cos.png

Figure 40 To obtain bucket information from the IBM Spectrum Protect Plus 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 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 for an Amazon S3 account.

_images/reference_objectstorage_bucket03azure.png

Figure 41 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 for an Amazon S3 account.

_images/reference_objectstorage_bucket04generic.png

Figure 42 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 S3 Compatible Storage, configure the required settings, and click Get Buckets.