1. REST API for Oracle Java Cloud Service
  2. Tasks
  3. Backups and Restorations

Update the Backup Configuration

post

/paas/api/v1.1/instancemgmt/{identityDomainId}/services/jaas/instances/{serviceId}/backupconfig

Updates the backup configuration for an Oracle Java Cloud Service instance. Specifically, you can update the following details:
  • Schedule for full and incremental backups
  • Default retention time for incremental backups and full on-demand backups; note that full scheduled backups are retained until their last related incremental backup is no longer available, if any
  • URI and user name for the object storage container or bucket that is used to store backups

To disable a scheduled full or incremental backup, set the fullBackupSchedule or incrementalBackupSchedule value, respectively, to null. For example: {"fullBackupSchedule": null}.

To disable and renable the backup service for a service instance, use the backups parameter. When disabled, on-demand backups cannot be performed and scheduled backups will not run. When the backup service is reenabled, scheduled backups will resume at the next scheduled time. In other words, missed scheduled backups are not run.

If you specified a notification email address when you created the service instance, Oracle Java Cloud Service automatically disables backups and notifies you after three consecutive scheduled backups failures of the same error. If you did not specify an email, Oracle Java Cloud Service automatically disables backups after seven consecutive failures of scheduled backups. When updating the backup configuration, correct the cause of the failure and also re-enable backups using the backups parameter.

For complete information about scheduled automated backups, contents of backups, and where backups are stored, see About Backup and Restoration in Administering Oracle Java Cloud Service.

Request

Supported Media Types
Path Parameters
Header Parameters
Body ()
The request body defines the details of the backup configuration update request. Specify only those attributes that you want to update.
Root Schema : backupconfig-postrequest
Type: object
The request body defines the details of the backup configuration update request. There are no required attributes, but you must specify the backups parameter to disable or reenable the backup service for the specified service instance.
Show Source
  • State of the backup service you want to set for the specified Oracle Java Cloud Service instance. Valid value: DISABLE, ENABLE, or UNCHANGED (default).

    When the backup service is disabled, both on-demand and scheduled backups are disabled. The following operations are also not permitted on the service instance when the backup service is disabled:

    • Update the backup configuration (except to reenable)
    • Restore from an existing backup
    • Apply a patch
    • Rollback a patch

    Scheduled backups do not run when the backup service is disabled. Upon reenabling the backup service, scheduled backups will resume at the next scheduled time. In other words, missed scheduled backups are not run.

  • Where to store service instance backups.

    This is the URI of an existing object storage container or bucket.

    On Oracle Cloud Infrastructure Classic and Oracle Cloud at Customer, specify the container using one of the following formats:

    • Storage-<identitydomainid>/<containername>
    • <storageservicename>-<identitydomainid>/<containername>
    • <restEndPointURL>/<containerName>
    The format to use to specify the container name depends on the URL of your Oracle Cloud Infrastructure Object Storage Classic account. To identify the URL of your account, see Finding the REST Endpoint URL for Your Cloud Account in Using Oracle Cloud Infrastructure Object Storage Classic.

    On Oracle Cloud Infrastructure, specfiy the object storage bucket using the following format:

    https://swiftobjectstorage.<region>.oraclecloud.com/v1/<namespace>/<bucket>

    To find out your namespace, sign in to the Oracle Cloud Infrastructure web console, click the tenancy name, and look for the Object Storage Namespace field.

    Example:

    https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/acme/mybucket

    Also note the following on all cloud deployments:

    • If you change the object storage container or bucket name, any existing backups in the previous container or bucket will remain there and be available for service restoration until the retention period has elapsed.
    • If you try to change the name and the object storage user credentials (cloudStorageUser and cloudStoragePassword), the URI will not be updated to the new value if at least one existing backup in the old container or bucket cannot be used (because the old container or bucket cannot be accessed with the new credentials).

  • Password for the object storage user.

    On Oracle Cloud Infrastructure Classic and Oracle Cloud at Customer, this is the password for the Oracle Cloud Infrastructure Object Storage Classic user who has read and write access to the container that is specified in cloudStorageContainer.

    If a service instance on Oracle Cloud Infrastructure Classic is using Oracle Identity Cloud Service, this attribute is not required if the current cloud user is entitled to use Oracle Cloud Infrastructure Object Storage Classic.

    On Oracle Cloud Infrastructure, this is the Auth token generated in Oracle Cloud Infrastructure for the user specified in cloudStorageUser.

  • User name for the object storage user.

    On Oracle Cloud Infrastructure Classic and Oracle Cloud at Customer, this is the user name for the Oracle Cloud Infrastructure Object Storage Classic user who has read and write access to the container that is specified in cloudStorageContainer.

    If a service instance on Oracle Cloud Infrastructure Classic is using Oracle Identity Cloud Service, this attribute is not required if the current cloud user is entitled to use Oracle Cloud Infrastructure Object Storage Classic.

    On Oracle Cloud Infrastructure, this is the user name for the Oracle Cloud Infrastructure Object Storage user.

  • Number of days incremental backups and full on-demand backups are retained. This value defaults to 30. Full scheduled backups are retained until their last related incremental backup is no longer available, if any.

    Any change to the default retention value will affect new backups as well as existing backups. This means if you change the value to a smaller number, existing backups that meet the updated retention policy will be deleted during the next backup or next scheduled maintenance cycle.

  • Flag that specifies whether a scheduled Oracle Java Cloud Service instance backup will include a backup of the associated database deployment.

    A value of false means a backup of the associated database deployment is coordinated and enabled. A value of true means a coordinated database deployment backup is not performed (disabled) during a scheduled backup of this service instance.

    If the Oracle Java Cloud Service instance has backupDestination set to BOTH and the instance is associated with a database deployment that has backupDestination set to NONE, a scheduled Oracle Java Cloud Service instance backup does not include a backup of the associated database.

    Note: This attribute is not applicable to an Oracle Java Cloud Service instance that uses Oracle Database Exadata Cloud Service for the required infrastructure schema. The attribute is ignored if it is specified in the service instance backup configuration. This attribute is also not applicable to service instances that use an Oracle Autonomous Transaction Processing database or Oracle Cloud Infrastructure Database (DB system) to host the infrastructure schema. Coordinated backups are not available for such service instances.

  • fullBackupSchedule
    Schedule for the next full backup.

    By default, full backups are initiated weekly starting 12 hours after an instance was created, rounded to the nearest five-minute interval.

    Note: Though not recommended, you can disable full backups temporarily by setting this attribute to null.

  • incrementalBackupSchedule
    Schedule for the next incremental backup.

    By default, incremental backups are initiated every day except the day that full backups are initiated.

    Note: Though not recommended, you can disable incremental backups temporarily by setting this attribute to null.

  • Number of days to retain the copies of backups on a dedicated storage volume. Default is 7 days.

    The local retention value cannot be larger than the default retention value (specified by defaultRetention).

    Copies of full scheduled backups are retained until the local copy of their last related incremental backup is no longer available, if any.

    Any change to the local retention value will affect new backup copies as well as existing copies. This means if you change the value to a smaller number, existing backup copies that meet the updated retention policy will be deleted during the next backup or next scheduled maintenance cycle.

Nested Schema : fullBackupSchedule
Type: array
Schedule for the next full backup.

By default, full backups are initiated weekly starting 12 hours after an instance was created, rounded to the nearest five-minute interval.

Note: Though not recommended, you can disable full backups temporarily by setting this attribute to null.

Show Source
Nested Schema : incrementalBackupSchedule
Type: array
Schedule for the next incremental backup.

By default, incremental backups are initiated every day except the day that full backups are initiated.

Note: Though not recommended, you can disable incremental backups temporarily by setting this attribute to null.

Show Source
Nested Schema : backupschedule
Type: object
Attributes for fullBackupSchedule and incrementalBackupSchedule.
Show Source
Back to Top

Response

Supported Media Types

202 Response

Accepted. The Location header returns a URI that can be used to view the job status, as described in View the Status of an Operation by Job Id.
Body ()
Root Schema : postrequest-response
Type: object
The response body contains information about the operation.
Show Source

400 Response

Bad Request. Returned when you try to update the backup configuration when the backup service for the service instance has been disabled.
Back to Top

Examples

The following example shows how to update the backup configuration for an Oracle Java Cloud Service instance by submitting a POST request on the REST resource using cURL.

Note: The command in this example uses the URL structure https://rest_server_url/resource-path, where rest_server_url is the REST server to contact for your identity domain (or Cloud Account). See Send Requests.

cURL Command

curl -i -X POST -u username:password -d @backupconfig.json -H "Content-type:application/json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/backupconfig

Example of Request Body

The following shows an example of the request document in JSON format to change the automatic backup schedule. Include only those parameters that you want changed.

{
   "fullBackupSchedule":
   {
      "hour":"5",
      "dayOfWeek":"Sun"
   },
   "incrementalBackupSchedule":
   {
      "hour":"3"
   }
}

Note: You cannot change the backup configuration when the backup service for the specified service instance is in a DISABLED state.

The following shows an example of the request document in JSON format to disable the backup service for the specified service instance.

Note that the request payload should not include other parameters as supported in the backup configuration because you are disabling the backup service.

{
    "backups": "DISABLE"
}

The following shows an example of the request document in JSON format to enable the backup service for the specified service instance.

{
    "backups": "ENABLE",
	"cloudStorageUser":"<username for jcs backup>",
	"cloudStoragePassword":"<Auth token to access OCI object storage bucket>"
}

Note that the request payload can include other parameters as supported in the backup configuration when you re-enable the backup service. For example, if Oracle Java Cloud Service automatically disabled backups on the service instance after consecutive failures, then also correct the cause of the failure.

Example of Response Header and Body

The following shows an example of the response. The Location header returns the URI that can be used to view the job status. See View the Status of an Operation by Job Id. 

HTTP/1.1 202 Accepted
Date: Sat, 22 Apr 2017 19:38:50 GMT
Location: https://rest_server_url/paas/api/v1.1/activitylog/ExampleIdentityDomain/job/1882092
Content-Type: application/json
...
{
    "operationName":"backup-config-update",
    "target_uri":"https:\/\/rest_server_url\/paas\/api\/v1.1\/instancemgmt\/ExampleIdentityDomain\/services\/jaas\/instances\/ExampleInstance\/backupconfig",
    "job_id":"1882092"
}
Back to Top