Consume an app deployed on SQL Server Big Data Clusters using a RESTful web service
Applies to: SQL Server 2019 (15.x)
This article describes how to consume an app deployed on a SQL Server big data cluster using a RESTful web service.
The Microsoft SQL Server 2019 Big Data Clusters add-on will be retired. Support for SQL Server 2019 Big Data Clusters will end on February 28, 2025. All existing users of SQL Server 2019 with Software Assurance will be fully supported on the platform and the software will continue to be maintained through SQL Server cumulative updates until that time. For more information, see the announcement blog post and Big data options on the Microsoft SQL Server platform.
- SQL Server big data cluster
- Azure Data CLI (
- An app deployed using either azdata or the App Deploy extension
When the application's yaml specification file specifies a schedule, the application will be triggered via a cron job. If your big data cluster is deployed on OpenShift, launching the cron job requires additional capabilities. See the details regarding security considerations on OpenShift for specific instructions.
After you have deployed an application to your SQL Server 2019 Big Data Clusters, you can access and consume that application using a RESTful web service. This enables integration of that app from other applications or services (for example, a mobile app or website). The following table describes the application deployment commands that you can use with azdata to get information about the RESTful web service for your app.
azdata app describe
You can get help with the
--help parameter as in the following example:
azdata app describe --help
The following sections describe how to retrieve an endpoint for an application and how to work with the RESTful web service for application integration.
Retrieve the endpoint
Big Data Clusters provides endpoints that you can access and consume that application using a RESTful web service, the main purpose is to facilities the interaction with other web or mobile applications and being more proactive for those microservices architecture. The azdata app describe command provides detailed information about the app including the end point in your cluster. This is typically used by an app developer to build an app using the swagger client and using the webservice to interact with the app in a RESTful manner.
Describe your app by running a command similar to the following example:
azdata app describe --name add-app --version v1
Note the IP address (
10.1.1.3 in this example) and the port number (
30080) in the output.
One of the other ways to get this information is doing right-click Manage on the server in Azure Data Studio where you'll find the endpoints of the services listed.
Generate a JWT access token
To access the RESTful web service for the app you've deployed you first have to generate a JWT Access token. The URL for the access token depends on the version of Big Data Cluster.
|CU1 and later
From the output of previous example, CU4 release and the IP address of controller (10.1.1.3 in the example) and the port number (30080), the URL would look like the following:
For version information, see Release history.
Open the appropriate URL in your browser using the IP address and port you retrieved running the
describe command above. Sign in with the same credentials you used for
Paste the contents of the
swagger.json into the Swagger Editor to understand what methods are available:
app is GET method and to get the
token would use POST method. Since the authentication for apps uses JWT tokens, you'll need to get a token my using your favorite tool to make a POST call to the
token method. With the same example, the URL to get JWT token would look like the follows:
Here is an example of how to do just that in Postman:
The output of this request will give you a JWT
access_token, which you'll need to call the URL to run the app.
Execute the app using the RESTful web service
There are multiple ways to consume an app on SQL Server Big Data Clusters, you can choose to use azdata app run command. This section will demonstrate how to use common developer tools such as Postman to execute the app.
You can open the URL for the
swagger that was returned when you ran
azdata app describe --name [appname] --version [version] in your browser, which should be similar to
You'll have to log in with the same credentials you used for
azdata login. With the same example, the command would look like the follows :
azdata app describe --name add-app --version v1
The contents of the
swagger.json you can paste into Swagger Editor. You'll see that the web service exposes the
run method, and underneath it went through application proxy, which is a web API that authenticates users and then routes the requests through to the applications. Notice that the Base URL displayed at the top. You can use tool of your choice to call the
run method (
https://[IP]:30778/api/app/[appname]/[version]/run), passing in the parameters in the body of your POST request as json.
In this example, we'll use Postman. Before making the call, you'll need to set the
Bearer Token and paste in the token you retrieved earlier. This will set a header on your request. See the screenshot below.
Next, in the requests body, pass in the parameters to the app you're calling and set the
When you send the request, you'll get the same output as you did when you ran the app through
azdata app run:
You've now successfully called the app through the web service. You can follow similar steps to integrate this web service in your application.
For more information about SQL Server Big Data Clusters, see What are SQL Server 2019 Big Data Clusters.