The following sections describes the Oracle Virtual Assembly Builder Web Service API:
The Oracle Virtual Assembly Builder Deployer provides logical operations which are used in the Web service and CLI operations. Some operations are asynchronous and the status of these operations can be tracked with a describeRequests
operation.
The complete API reference for the operations are described in the following chapters:
Oracle Virtual Assembly Builder Deployer provides logical administrative operations for configuring targets, which reference pools in virtualization environments. All of these operations are synchronous.
Due to the differences in how virtualization environments work and how we interact with them, configuration of these involves two steps.
Creating targets using the CreateTarget
operation. This step is required for Oracle VM
Adding user configuration information for a named user to a target using AddTargetUser
. For more details, see Section 3.3, "AddTargetUser" in Chapter 3, "API Reference: Administrative Operations".
Operations for adding users are not provided in these administrative operations. It is intended that these operations be performed directly against the LDAP server by security administrators authorized for such duties.
The first operation when using the Oracle Virtual Assembly Builder Deployer is to upload an assembly archive to the Deployer's repository using the uploadAssemblyArchive
operation.
You can register the uploaded assembly archive with one or more targets using the registerAssemblyArchive
operation. The details of registration are specific to the target type. For Oracle VM, registration includes uploading the assembly archive to the Deployer and registering the templates with a target within the Oracle VM system.
After an assembly archive has been registered with a target, you can create one or more assembly instances for that registration using the createAssemblyInstance
operation. An assembly instance is a context used to manage the lifecycle of VM instances for the assembly defined by the assembly archive. When creating an assembly instance, a deployment plan must be provided which defines the environment-specific details of the assembly managed through the assembly instance.
Once an assembly instance has been created for an assembly archive, you can initiate a deployment operation. During deployment, the initial instances for the assembly defined by the assembly archive are created and started. As this is done, the Deployer interacts with reconfiguration logic embedded in the initialization scripts of the instances which configures networks and mounted disk volumes and also configures the application stack for the environment. These interactions configure connections between instances that are created when the application stack starts up.
Once an assembly instance has been deployed, a number of other lifecycle operations can be applied to the running system such as scale
which increases or decreases the number of running instances for an appliance within the assembly. There are also operations to stop and start all instances of the deployment, which are used for bringing the application offline and back online.
Operations against the Web service are made by posting an HTTP request to the Deployer's context path. The request includes a request parameter that defines the action followed by zero or more request parameters that define arguments for the operation. See Section 2.5.2, "Query String Pattern" below for more details.
Action= action¶m1=value¶m2=value...
For an array of values, use the same parameter name multiple times in the query string. For example:
Action= action¶m1=value¶m2=value¶m2=value...
Chapter 3, "API Reference: Administrative Operations"describes all of the operations exposed by the admin Web service. Details of the types included in the "Response Content" column may be found in the schema in Appendix A, "Web Service Schema".
Table 2-1 shows how error handling is performed for the Web service.
Table 2-1 Web Service Error Handling
Responsible for Error | HTTP Status Code | Response Content XML Element |
---|---|---|
User |
4xx |
ErrorResult (type=USER) |
Service |
5xx |
ErrorResult (type=SERVICE) |
Note:
In the case of an error, there may not be any content (ErrorResult
) in the response. If the HTTP status code is generated by the servlet container, then there will not be any content in response. If the HTTP response is generated by the Oracle Virtual Assembly Builder Deployer, then most often there will be content in response, except when an unexpected service error occurs.
You can find the schema for the Web service in Appendix A, "Web Service Schema". This schema includes definitions for the response content items included in the table of actions, above.
Operations against the Web service are made by posting an HTTP request to the Deployer's context path. The request includes a request parameter that defines the action followed by zero or more request parameters that define arguments for the operation. See Section 2.5.2, "Query String Pattern" below for more details.
As described in Section 2.1, "Operations", some operations may initiate an asynchronous action. The operations exposed by the Web service are the same as is described for the logical operations described earlier.
Action= action¶m1=value¶m2=value...
For an array of values, use the same parameter name multiple times in the query string. For example:
Action= action¶m1=value¶m2=value¶m2=value...
Chapter 4, "API Reference: Deployer Operations" describes all of the operations exposed by the Deployer Web service. Details of the types included in the "Response Content" column may be found in the schema in Appendix A, "Web Service Schema".
Table 2-2 shows how error handling is performed for the Deployer Web service.
Table 2-2 Web Service Error Handling
Responsible for Error | HTTP Status Code | Response Content XML Element |
---|---|---|
User |
4xx |
ErrorResult (type=USER) |
Service |
5xx |
ErrorResult (type=SERVICE) |
Note:
In the case of an error, there may not be any content (ErrorResult
) in the response. If the HTTP status code is generated by the servlet container, then there will not be any content in response. If the HTTP response is generated by the Oracle Virtual Assembly Builder Deployer, then most often there will be content in response, except when an unexpected service error occurs.
You can find the schema for the Web service in Appendix A, "Web Service Schema". This schema includes definitions for the response content items included in the table of actions, above.