Oracle Cloud Infrastructure offers many useful services that your organization and apps could use, and in some cases you might want to leverage them from an Oracle Visual Builder app. An easy way to do that is to use the REST APIs these services provide.
This post will walk you through the steps to create a Service Connection for the OCI REST API in your Visual Builder application. You will be able to access your OCI account directly from your new application and perform any of the available API commands. For example, you could:
- Create an application that allows your users to start and stop compute instances in specific compartments, without having to give them access to your cloud console.
- Integrate OCI Notifications into your application to send alerts and messages to Oracle Functions, email, SMS, and message delivery partners, including Slack, PagerDuty, and ServiceNow.
There are many things you can do, this post will get you started.
Prerequisites
- Oracle cloud account.
- Cloud user with permissions to use the REST API.
User API key
In order to access the REST API you will need an API key.
To upload or create a new key:
- Log into your cloud account and open your User Settings.
- Under Resources, click on "API Keys".
- If you do not already have an API Key setup that you would like to use, click the "Add API Key" button.
If you have an API Key Pair that is not setup on this cloud account, select "Choose Public Key File" to upload it or select "Paste Public Key" to copy and paste it.
Important: You are only adding the public key here. Do not upload or paste your private key.
If you need a new key, select "Generate API Key Pair" and download the Private Key. The public key for this new pair will be saved in your API Keys. You can also download the public key if you'd like, but you won't need it for this example.
Save the Private Key in a secure location, this key can be used to access your account.
- Open the menu to the right of your key and click "View Configuration File".
- Copy the API Key Fingerprint and Configuration File Preview information, you'll need this later.
- For this example I will be using the Compute Instances API which requires a Compartment OCID.
In the cloud console menu, open Identity & Security / Compartments.
- Locate the compartment that contains the instances you want to work with and copy it's OCID.
Save this and the above information, you will need it later to connect to the API.
Visual Builder
Open Visual builder and create a new application.
Create a Service Connection
This section will show you how to create a Service Connection to the Core Services API / Instance / ListInstances endpoint. The authentication steps will be the same for other endpoints, but you may need to customize the REST calls.
- Create a new Service Connection.
- Select Define by Endpoint.
- Enter the URL for the API you want to use. In this example I'm using Core Services API / Instance / ListInstances. The URL for the Ashburn region is "https://iaas.us-ashburn-1.oraclecloud.com/20160918/instances".
- Set the method to GET.
- Set the Action Hint to "Get Many".
- Click Next.
- Enter a Service Name and Title.
- Change to the "Server" Tab.
- Under Authentication choose "Oracle Cloud Infrastructure API Signature 1.0"
- Click the pencil icon to edit the Key Id. This is where you'll need the information you copied in the first step.
- Enter your Key Id. This will be your "TenancyOCID/UserOCID/KeyFingerprint" found in the information you saved before.
The 3 pieces of data are separated with a "/". There should be no spaces in this string. - Enter the private key that you saved.
- Click Save.
The remaining steps in this post cover how to setup the specific "List Instances" API endpoint. Other endpoints may have different steps.
- Switch to the Operation tab.
- Enter an Endpoint ID.
- Switch to the Request tab.
- Click "Add Dynamic Query Parameter"
- Set the Name to "compartmentId" and mark it as Required.
- Switch to the Test Tab.
- Under the Query Parameters tab enter the Compartment OCID from above in the Value for compartmentId.
- Click "Send Request".
- You should get a response similar to this.
- Click "Save as Example Response.
- Click "Create".
Quick Test Application
Now that you have a working Service Connection, you can use it in your Visual Builder application the same way you would use any other Service Connection.
The following steps will show you how to make a simple "proof of concept" application for the List Instances Service Connection.
- Create a new Visual Builder Application.
- Enter an Application Name.
- Click Finish.
- In the left menu, select the Web Apps icon.
- Click the new "Web Application" button.
- Enter an Application Name.
- Click Create.
- Under the Data Tab, expand Services/OCI-Instances/Other Endpoints.
- Drag "Get Many" service and drop it in the new web app.
- In the "Render as" menu, choose "Table".
- Under the Endpoint Structure select
- displayName
- shape
- lifecycleState
- Click Next.
- Under Target, click on compartmentId*.
Normally, you would create a page variable set as the value of a component that you could use to choose the compartment. This is only a proof of concept so we'll take the easy road and set it as a static value. - Select Static Content.
- Enter the Compartment OCID from above.
- Click Finish.
- Make sure you're in "Design" mode.
- Select the table and expand it to 12 columns.
You should see the displayName, shape and lifecycleState of the compute instances that are in the chosen Compartment.
Jump back over to your OCI Console and start or stop one of the instances, then refresh your app to see that the status is being displayed correctly.
If you'd like to have a little extra fun, you could add buttons on each row to start and stop the compute instance from your new Visual Builder application.
Hint: Add a POST endpoint to the instances Service Connection using an Instance Action.