Spectra Logic

1-800-833-1132 : 1-303-449-6400

Register Amazon S3 Target

Description

Connect to and register the specified Amazon S3 target as a replication target for the BlackPearl system.

Notes:

§	Only Amazon Web Services (AWS) S3 is qualified as an Amazon S3 target. Other S3 services have not been tested.

§	You must include either a data_path_endpoint or a region. If you include both a Data Path End Point and a Region, the BlackPearl system uses the Data Path End Point and ignores the Region.

§	You cannot use the same Data Path End Point or Region, and Access Key for multiple Amazon S3 targets as this could cause data conflicts.

Requests

Syntax

POST http[s]://{datapathDNSname}/_rest_/s3_target​?access_key={string}&name={string}​&secret_key={string}​

[&auto_verification_frequency_in_days={32‑bit integer}]​[&cloud_bucket_prefix={string}][&cloud_bucket_suffix={string}][&data_path_end_point={string}]​[&default_read_preference=MINIMUM_LATENCY|AFTER_ONLINE_POOL|​AFTER_NEARLINE_POOL​|AFTER_NON_EJECTABLE_TAPE​|LAST_RESORT​|NEVER]​[&https=TRUE|FALSE[&name={string}][&offline_data_staging_window_in_tb={64-bit integer}]​[&permit_going_out_of_sync=TRUE|FALSE][&proxy_domain={string}][&proxy_host={string}][&proxy_password={string}][&proxy_port={string}][&proxy_username={string}][&region={string}][&secret_key={string}][&staged_data_expiration_in_days={string}]

 

Request Parameters 

Parameter	Description	Required
access_key	The the S3 Access Key of the user for the Amazon S3 account.	yes
name	The name for the Amazon S3 target.	yes
secret_key	The secret key associated with the AccessKey.	yes
auto_verify_ frequency_in_days	The frequency at which a full verify of the data on the target is scheduled. If null (default), no full verify is scheduled. It is useful to schedule auto verify when the target is a storage domain in a data policy using replicate deletes. The verify ensures that deletes replicate in a timely manner.	no
cloud_bucket_ prefix	The Amazon S3 target bucket prefix. The prefix must must adhere to the Amazon S3 naming requirements. Bucket names on the BlackPearl system must be unique within the system, but bucket names in Amazon S3 must be unique across the world. To permit friendlier, shorter local bucket names on the BlackPearl system while avoiding naming conflicts with Amazon S3, the BlackPearl system optionally adds the defined Cloud Bucket Prefix to the BlackPearl bucket name when it replicates the bucket.	no
cloud_bucket_ suffix	The Amazon S3 target bucket suffix. The suffix must must adhere to the Amazon S3 naming requirements. Bucket names on the BlackPearl system must be unique within the system, but bucket names in Amazon S3 must be unique across the world. To permit friendlier, shorter local bucket names on the BlackPearl system while avoiding naming conflicts with Amazon S3, the BlackPearl system optionally adds the defined Cloud Bucket Suffix to the BlackPearl bucket name when it replicates the bucket.	no
data_path_end_ point	The IPv4 address or DNS name for the data path of the AWS cloud service.	no
default_read_ preference	When it is preferable to read from the Amazon S3 target rather than the replication source. Values: MINIMUM_LATENCY, AFTER_ONLINE_POOL, AFTER_NEARLINE_POOL, AFTER_NON_EJECTABLE_TAPE, LAST_RESORT, NEVER. See read_preference.	no
https	Whether the BlackPearl system uses the HTTPS protocol to setup and replicate data to the target. Values: TRUE, FALSE.	no
offline_data_ staging_window_ in_tb	The maximum size, in TB, of the window available for staging data that is offline (in Glacier) so that it can be read.	no
permit_going_out_of_sync	Whether a target is allowed to be out of sync with the source. By default, if the data policy specifies that the BlackPearl system must replicate local actions, actions that the system cannot replicate fail. You can temporarily set this parameter to TRUE in order to operate in full capacity locally while one or more targets is down for a prolonged period of time. Values: TRUE, FALSE (default) Note: This parameter is deprecated.	no
proxy_domain	The domain name for the proxy server.	no
proxy_host	The host name or IP address for the proxy server which the BlackPearl system connects.	no
proxy_password	The password used when connecting through the proxy server.	no
proxy_port	The proxy server port through which the BlackPearl system connects.	no
proxy_username	The username used when connecting through the proxy server.	no
region	The world region where the Amazon S3 target is physically located. Values: US_EAST_1, US_WEST_1, US_WEST_2, EU_WEST_1, EU_CENTRAL_1, AP_SOUTH_1, AP_SOUTHEAST_1, AP_SOUTHEAST_2, AP_NORTHEAST_1, AP_NORTHEAST_2, SA_EAST_1, CN_NORTH_1, GOV_CLOUD	no
staged_data_ expiration_in_days	The number of days before the pre‐staged copy of data can expire. If the BlackPearl system does not retrieve all of the data before the copy expires, it has to go through the process of pre‐staging it again, incurring additional delays and costs.	no

Responses

Response Elements

<Data>

   <AccessKey>{string}</AccessKey>

   <AutoVerifyFrequencyInDays>{string}</AutoVerifyFrequencyInDays>

   <CloudBucketPrefix>{string}</CloudBucketPrefix>

   <CloudBucketSuffix>{string}</CloudBucketSuffix>

   <DataPathEndPoint>{string}</DataPathEndPoint>

   <DefaultReadPreference>
      MINIMUM_LATENCY|AFTER_ONLINE_POOL|AFTER_NEARLINE_POOL
      |AFTER_NON_EJECTABLE_TAPE|LAST_RESORT|NEVER
   </DefaultReadPreference>

   <Https>TRUE|FASLE</Https>

   <Id>{string}</Id>

   <LastFullyVerified>{string}</LastFullyVerified>

   <Name>{string}</Name>

   <OfflineDataStagingWindowInTb>

     {64-bit integer}

   </OfflineDataStagingWindowInTb>

   <PermitGoingOutOfSync>TRUE|FALSE</PermitGoingOutOfSync>

   <ProxyDomain>{string}</ProxyDomain>

   <ProxyHost>{string}</ProxyHost>

   <ProxyPassword>{string}</ProxyPassword>

   <ProxyPort>{64-bit integer}</ProxyPort>

   <ProxyUsername>{string}</ProxyUsername>

   <Quiesced>NO|PENDING|YES</Quiesced>

   <Region>{string}</Region>

   <SecretKey>{string}</SecretKey>

   <StagedDataExpirationInDays>

     {64-bit integer}

   </StagedDataExpirationInDays>

   <State>ONLINE|OFFLINE|LIMITED_ACCESS</State>

</Data>

where the response elements are defined as follows:

Parameter	Description
Data	The container for the response.
AccessKey	The the S3 Access Key of the user for the Amazon S3 account.
AutoVerify FrequencyInDays	The frequency at which a full verify of the data on the target is scheduled. If null, no full verify is scheduled. It is useful to schedule auto verify when the target is a storage domain in a data policy using replicate deletes. The verify ensures that deletes replicate in a timely manner.
CloudBucketPrefix	The Amazon S3 target bucket prefix. Bucket names on the BlackPearl system must be unique within the system, but bucket names in Amazon S3 must be unique across the world. To permit friendlier, shorter local bucket names on the BlackPearl system while avoiding naming conflicts with Amazon S3, the BlackPearl system optionally adds the defined Cloud Bucket Prefix to the BlackPearl bucket name when it replicates the bucket.
CloudBucketSuffix	The Amazon S3 target bucket suffix. Bucket names on the BlackPearl system must be unique within the system, but bucket names in Amazon S3 must be unique across the world. To permit friendlier, shorter local bucket names on the BlackPearl system while avoiding naming conflicts with Amazon S3, the BlackPearl system optionally adds the defined Cloud Bucket Suffix to the BlackPearl bucket name when it replicates the bucket.
DataPathEndpoint	The IPv4 address or DNS name for the data path of the AWS cloud service.
DefaultRead Preference	When it is preferable to read from the Amazon S3 target rather than the replication source. Values: MINIMUM_LATENCY, AFTER_ONLINE_POOL, AFTER_NEARLINE_POOL, AFTER_NON_EJECTABLE_TAPE, LAST_RESORT, NEVER. See read_preference.
Https	Whether the BlackPearl system uses the HTTPS protocol to setup and replicate data to the target. Values: TRUE, FALSE.
Id	The UUID for the Amazon S3 target instance.
LastFullyVerified	The date and time data on the target was last fully verified in the format YYYY-MM-DDThh:mm:ss.xxxZ.
Name	The name for the Amazon S3 target.
OfflineDataStagingWindowInTb	The maximum size, in TB, of the window available for staging data that is offline (in Glacier) so that it can be read.
PermitGoingOutOfSync	Whether a target is allowed to be out of sync with the source. See permit_going_out_of_sync. Note: This parameter is deprecated.
ProxyDomain	The domain name for the proxy server.
ProxyHost	The host name or IP address for the proxy server which the BlackPearl system connects.
ProxyPassword	The password used when connecting through the proxy server.
ProxyPort	The proxy server port through which the BlackPearl system connects.
ProxyUsername	The username used when connecting through the proxy server.
Quiesced	Whether the Amazon S3 target is in a temporarily inactive state. Values: NO, PENDING, YES
Region	The world region where the Amazon S3 target is physically located. Values: US_EAST_1, US_WEST_1, US_WEST_2, EU_WEST_1, EU_CENTRAL_1, AP_SOUTH_1, AP_SOUTHEAST_1, AP_SOUTHEAST_2, AP_NORTHEAST_1, AP_NORTHEAST_2, SA_EAST_1, CN_NORTH_1, GOV_CLOUD
SecretKey	The secret key associated with the AccessKey.
StagedData ExpirationInDays	The number of days before the pre‐staged copy of data can expire. If the BlackPearl system does not retrieve all of the data before the copy expires, it has to go through the process of pre‐staging it again, incurring additional delays and costs.
State	The state of the Amazon S3 target. Values: ONLINE, OFFLINE, LIMITED_ACCESS

Example

Sample Request

This request registers an Amazon S3 target with the data path end point ‘DataPath’, the S3 Access Key ‘c381Y3RyYQ==’, the S3 Secret Key ‘d7pJBeAN’, and the name ‘TargetS3’ as a replication target for the BlackPearl system.

POST http[s]://blackpearl-hostname/_rest_/s3_target​?admin_auth_id=c381Y3RyYQ==&admin_secret_key=d7pJBeAN​&data_path_end_point=DataPath&name=TargetS3 HTTP/1.1

Sample Response

HTTP/1.1 201 CREATED
<Data>

   <AccessKey>c381Y3RyYQ==</AccessKey>

   <AutoVerifyFrequencyInDays/>

   <CloudBucketPrefix/>

   <CloudBucketSuffix/>

   <DataPathEndPoint>DataPath</DataPathEndPoint>

   <DefaultReadPreference>MINIMUM_LATENCY</DefaultReadPreference>

   <Https>TRUE</Https>

   <Id>771c3371-8276-45ce-a21c-a3bfd1ca5caa</Id>

   <LastFullyVerified/>

   <Name>TargetS3</Name>

   <OfflineDataStagingWindowInTb>64</OfflineDataStagingWindowInTb>

   <PermitGoingOutOfSync>FALSE</PermitGoingOutOfSync>

   <ProxyDomain/>

   <ProxyHost/>

   <ProxyPassword/>

   <ProxyPort/>

   <ProxyUsername/>

   <Quiesced>NO</Quiesced>

   <Region>US_WEST_2</Region>

   <SecretKey>d7pJBeAN</SecretKey>

   <StagedDataExpirationInDays>30</StagedDataExpirationInDays>

   <State>ONLINE</State>

</Data>