Oracle SOA Cloud Service: using Rest API to start and stop instances

Oracle SOA Cloud Service: using Rest API to start and stop instances

Published on: Category: Oracle

In this article, Qualogy's Eduardo Cordeiro shares some tips about how to use Oracle Cloud Rest API to start and stop your SOA CS stack. This article is based on the official Oracle cloud documentation.

Use case

Even though you can always use the cloud dashboard console to control your cloud instances, it is useful to have some scripts scheduled to start and stop when you want to save your credits, mainly for non-production environment. If you want to keep your instances up only 5 days a week, 8h per day (not 24x7), you are probably searching for a way to automate this process.

Using Rest API to manage SOA Cloud Service instances

In the Oracle documentation you will find all the available commands that can be executed to manage your instances. In this post I will use start and stop commands only. Additional to that, I will share how to start/stop your databases in the cloud.

The standard URL that you will use to execute your commands on SOA CS instances is:

https://soa_rest_url/paas/api/v1.1/instancemgmt/domain_name/services/SOA/instances/service_name/hosts/action

Where:

  • soa_rest_url: as a cloud client you are supposed to have your own Rest URL. You should be able to find it in your cloud SOA dashboard under REST API URL parameter. If you cannot find it, you can use the following entry. I found it in the internal Oracle documentation: https://psm.europe.oraclecloud.com
  • domain_name: this value will be available in your SOA cloud dashboard under Identity Service ID parameter. You can easily identify it because, by default, it will start with idcs- and will contain a long hash after that.
  • service_name: here you will provide the SOA instance name.
  • action: in my context, the actions will be start or stop.

In this post I will use cURL to call the REST endpoint. You can use different ways and applications for this. If you have any questions about how to execute it, please check the documentation in the link at the end of this post.

Start a SOA CS instance

The first step is to create a JSON file with the properties that will be used by the API to run the start command. The sample below is the property to start all resources in one specific instance. In my case, I saved this content in a file called start_soa.json.

  1. {
  2. "allServiceHosts" : true
  3. }
  4.  

The next step will be to execute the cURL command. I use a Windows desktop so I will run the cURL using “command”.

The standard cURL command to execute is:

  1. curl -i -X POST -u user:password -H "X-ID-TENANT-NAME:domain_name" -d @start_soa.json -H "Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json" https://soa_rest_url/paas/api/v1.1/instancemgmt/domain_name/services/SOA/instances/soa_instance/hosts/action

Where:

  • user: this is your cloud user (not Weblogic user).
  • password: this is your cloud password (not Weblogic password).
  • domain_name: this value has already been described (it is available in your SOA cloud dashboard under Identity Service ID parameter. You can easily identify it because by default it will start with idcs- and will contain a long hash after that).
  • start_soa.json: this is the file with JSON properties, previously created in this post.
  • soa_rest_url: this is the SOA rest endpoint from your cloud datacenter. Es: https://psm.europe.oraclecloud.com
  • soa_instance: this is your SOA instance name.
  • action: in this case, the action is start.

Now, using command, go to the folder where you saved your start_soa.json file and run the following command. Remember to replace the highlighted parameters with your real values:

  1. curl -i -X POST -u USER:PASS -H "X-ID-TENANT-NAME:idcs-123456789abc" -d @start_soa.json -H "Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json" https://psm.europe.oraclecloud.com/paas/api/v1.1/instancemgmt/idcs-123456789abc/services/SOA/instances/MySOAInstance/hosts/start

The result for this command will be similar to the following:

  1. HTTP/1.1 202 Accepted
  2. Server: Oracle-Application-Server-11g
  3. Strict-Transport-Security: max-age=31536000;includeSubDomains
  4. Location: https://psm.europe.oraclecloud.com:443/paas/api/v1.1/activitylog/idcs-123456789abc/job/88888888
  5. X-ORACLE-DMS-ECID: ABCDE1234
  6. X-ORACLE-DMS-ECID: ABCDE1234
  7. X-Frame-Options: DENY
  8. Service-URI: https://psm.europe.oraclecloud.com:443/paas/api/v1.1/instancemgmt/idcs-123456789abc/services/SOA/MySOAInstance
  9. Retry-After: 60
  10. Content-Language: en
  11. Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json
  12. Vary: user-agent
  13. Date: Tue, 01 Jan 2019 12:00:00 GMT
  14. Connection: close
  15.  
  16. ​​​​​​​{"details":{"message":"Submitted job to [start] VMs in service [MySOAInstance] in domain [idcs-123456789abc].","jobId":"88888888"}}.

Stop a SOA CS instance

As before, the first step is to create a JSON file with the properties that will be used by the API to run the stop command. The sample below is the property to stop all resources in one specific instance. I saved this content in a file called stop_soa.json

  1. {
  2. "allServiceHosts" : true
  3. }

The standard cURL command to execute is the same as the one used to start. The only difference will be the JSON file name and the action (stop instead of start).

Using command, go to the folder where you saved your stop_soa.json file and run the following command. Remember to replace the highlighted parameters with your real values:

  1. curl -i -X POST -u USER:PASS -H "X-ID-TENANT-NAME:idcs-123456789abc" -d @stop_soa.json -H "Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json" https://psm.europe.oraclecloud.com/paas/api/v1.1/instancemgmt/idcs-123456789abc/services/SOA/instances/MySOAInstance/hosts/stop

The result for this command will be similar to the following:

  1. HTTP/1.1 202 Accepted
  2. Server: Oracle-Application-Server-11g
  3. Strict-Transport-Security: max-age=31536000;includeSubDomains
  4. Location: https://psm.europe.oraclecloud.com:443/paas/api/v1.1/activitylog/idcs-123456789abc/job/88888889
  5. X-ORACLE-DMS-ECID: ABCDE1234
  6. X-ORACLE-DMS-ECID: ABCDE1234
  7. X-Frame-Options: DENY
  8. Service-URI: https://psm.europe.oraclecloud.com:443/paas/api/v1.1/instancemgmt/idcs-123456789abc/services/SOA/MySOAInstance
  9. Retry-After: 60
  10. Content-Language: en
  11. Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json
  12. Vary: user-agent
  13. Date: Tue, 01 Jan 2019 12:00:00 GMT
  14. Connection: close
  15.  
  16. {"details":{"message":"Submitted job to [stop] VMs in service [MySOAInstance] in domain [idcs-123456789abc].","jobId":"88888889"}}.

Check the SOA CS status

To check the status of your SOA CS instance you can run another command, but a little differently:

  1. curl -i -X GET -u USER:PASS -H "X-ID-TENANT-NAME:idcs-123456789abc" https://psm.europe.oraclecloud.com/paas/core/api/v1.1/healthcheck/idcs-123456789abc/services/SOA/instances/MySOAInstance

The result for this command will be similar to the following:

  1. HTTP/1.1 200 OK
  2. Server: Oracle-Application-Server-11g
  3. Strict-Transport-Security: max-age=31536000;includeSubDomains
  4. X-ORACLE-DMS-ECID: ABCDE1234
  5. X-ORACLE-DMS-ECID: ABCDE1234
  6. X-Frame-Options: DENY
  7. X-Frame-Options: DENY
  8. Content-Language: en
  9. Content-Type: application/json
  10. Vary: user-agent
  11. Date: Tue, 01 Jan 2019 12:00:00 GMT
  12. Content-Length: 4122
  13. Connection: keep-alive

Together with this header you will receive a JSON response. In the example below, I will only show the part where you can validate the SOA stack status:

  1. {
  2. "timestamp": "2019-01-01T120:00:00.00+00:00",
  3. "collectionTime": "2019-01-01T12:00:00.000+00:00",
  4. "serviceId": 1234,
  5. "status": "UP",
  6. "domainName": "idcs-123456789abc",
  7. "components": {...},
  8. "dataQuality": {
  9. "message": "Health data complete"
  10. },
  11. "serviceType": "SOA",
  12. "serviceName": "MySOAInstance",
  13. "statusMessage": "Running"
  14. }

You will receive another message in case your server is still starting:

  1. {
  2. "serviceId": 1234,
  3. "domainName": "idcs-123456789abc",
  4. "components": {...},
  5. "dataQuality": {
  6. "message": "Monitoring operation for service MySOAInstance timed-out. Context id is 1234. Service is in starting state. If problem persists, please contact customer support"
  7. },
  8. "serviceType": "SOA",
  9. "serviceName": "MySOAInstance"
  10. }

Finally, if your server is shut down, you will receive a similar message:

  1. {
  2. "serviceId": 1234,
  3. "domainName": "idcs-123456789abc",
  4. "components": {...},
  5. "dataQuality": {
  6. "message": "Monitoring operation for service MySOAInstance timed-out. Context id is 1234. Service is in stopped state. If problem persists, please contact customer support"
  7. },
  8. "serviceType": "SOA",
  9. "serviceName": "MySOAInstance"
  10. }

Start/Stop a SOA CS Database instance

The standard cURL command should be executed on the database context like the example below. Depending on what activity you want to execute, inform the correct JSON file:

  1. curl -i -X POST -u user:password -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:domain_name" -d @action_db.json -H https://db_rest_url/paas/service/dbcs/api/v1.1/instances/domain_name/db_instance

Where:

  • user: this is your cloud user (not Weblogic user).
  • password: this is your cloud password (not Weblogic password).
  • domain_name: this value has already been described (it is available in your SOA cloud dashboard under Identity Service ID parameter. You can easily identify it because by default it will start with idcs- and will contain a long hash after that).
  • action_db.json: this is the file with JSON properties.
  • db_rest_url: this is the DB rest endpoint from your cloud datacenter. Note: usually it is not the same as the one used in the SOA rest API. Es: https://dbcs.emea.oraclecloud.com
  • db_instance: this is your SOA instance name.

The sample below is the property to start the DB instance. I saved this content in a file called start_db.json.

  1. {
  2. "lifecycleState" : "Start"
  3. }

Now, the property to stop the DB instance. In my example, I saved this content in a file called stop_db.json.

  1. {
  2. "lifecycleState" : "Stop"
  3. }

Using command, let’s start the database. Go to the folder where you saved your start_db.json file and run the following command. Remember to replace the highlighted parameters with your real values:

  1. curl -i -X POST -u USER:PASS -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:idcs-123456789abc" -d @start_db.json -H https://dbcs.emea.oraclecloud.com/paas/service/dbcs/api/v1.1/instances/idcs-123456789abc/MyDBInstance

The result for this command will be similar to the following:

 

  1. HTTP/1.1 202 Accepted
  2. Server: Oracle-Application-Server-11g
  3. Strict-Transport-Security: max-age=31536000;includeSubDomains
  4. Location: https://dbcs.emea.oraclecloud.com:443/paas/service/dbcs/api/v1.1/instances/idcs-123456789abc/status/control/job/88888898
  5. X-ORACLE-DMS-ECID: ABCDE1234
  6. X-ORACLE-DMS-ECID: ABCDE1234
  7. X-Frame-Options: DENY
  8. Service-URI: https://dbcs.emea.oraclecloud.com:443/paas/service/dbcs/api/v1.1/instances/idcs-123456789abc/MyDBInstance
  9. Retry-After: 30
  10. Content-Language: en
  11. Content-Type: text/plain
  12. Vary: user-agent
  13. Date: Tue, 01 Jan 2019 12:00:00 GMT
  14. Connection: close

Now let’s stop the database instance. Use the same cURL command, but replace the JSON file name:

  1. curl -i -X POST -u USER:PASS -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:idcs-123456789abc" -d @stop_db.json -H https://dbcs.emea.oraclecloud.com/paas/service/dbcs/api/v1.1/instances/idcs-123456789abc/MyDBInstance

The result for this command will be similar to the following:

  1. HTTP/1.1 202 Accepted
  2. Server: Oracle-Application-Server-11g
  3. Strict-Transport-Security: max-age=31536000;includeSubDomains
  4. Location: https://dbcs.emea.oraclecloud.com:443/paas/service/dbcs/api/v1.1/instances/idcs-123456789abc/status/control/job/88888899
  5. X-ORACLE-DMS-ECID: ABCDE1234
  6. X-ORACLE-DMS-ECID: ABCDE1234
  7. X-Frame-Options: DENY
  8. Service-URI: https://dbcs.emea.oraclecloud.com:443/paas/service/dbcs/api/v1.1/instances/idcs-123456789abc/MyDBInstance
  9. Retry-After: 30
  10. Content-Language: en
  11. Content-Type: text/plain
  12. Vary: user-agent
  13. Date: Tue, 01 Jan 2019 12:00:00 GMT
  14. Connection: close

Conclusion

Mixing the commands, you can create your own script to start and stop your whole SOA CS stack, including database and SOA instances. You can then use your own scheduler to execute them in the best date/time for you and your company.

Reference

Service Instances REST Endpoints: https://docs.oracle.com/en/cloud/paas/soa-cloud/scsap/api-service-instances.html

cURL Oracle wiki: https://docs.oracle.com/en/cloud/paas/soa-cloud/scsap/UsecURL.html

Rest API Status codes: https://docs.oracle.com/en/cloud/paas/soa-cloud/scsap/StatusCodes.html

Eduardo Barra Cordeiro
About the author Eduardo Barra Cordeiro

Eduardo is a Fusion Middleware Consultant with more than 20 years in IT world. In the last 9 years he has been working in the Oracle Fusion Middleware space, starting as a developer, then a developer lead in a global team, with team members from Brazil, India and USA. Since 2014 he started working in the architecture role, along with development teams for BPEL projects, supporting BPEL, OSB, BPM and BAM environments and supporting high availability WebLogic domains. Eduardo has more than 10 years of experience working in the agile world, achieved being a certified SCRUM Master and sometimes the role of Product Owner. In 2018 he started a new challenge moving to the Netherlands to work with Qualogy clients using his technical and soft skills.

More posts by Eduardo Barra Cordeiro
Comments
Reply