Consume an app deployed on SQL Server Big Data Clusters using a RESTful web service

Article
08/06/2024

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.

Important

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.

Prerequisites

SQL Server big data cluster
Azure Data CLI (azdata)
An app deployed using either azdata or the App Deploy extension

Note

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.

Capabilities

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.

Command	Description
`azdata app describe`	Describe application.

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

{
  "input_param_defs": [
    {
      "name": "x",
      "type": "int"
    },
    {
      "name": "y",
      "type": "int"
    }
  ],
  "links": {
    "app": "https://10.1.1.3:30080/app/addpy/v1",
    "swagger": "https://10.1.1.3:30080/app/addpy/v1/swagger.json"
  },
  "name": "add-app",
  "output_param_defs": [
    {
      "name": "result",
      "type": "int"
    }
  ],
  "state": "Ready",
  "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.

Version	URL
GDR1	`https://[IP]:[PORT]/docs/swagger.json`
CU1 and later	`https://[IP]:[PORT]/api/v1/swagger.json`

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:

   https://10.1.1.3 :30080/api/v1/swagger.json

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. Sign in with the same credentials you used for azdata login.

Paste the contents of the swagger.json into the Swagger Editor to understand what methods are available:

API Swagger

Notice the 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:

   https://10.1.1.3 :30080/api/v1/token

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.

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 https://[IP]:[PORT]/app/[appname]/[version]/swagger.json.

Note

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

Next steps

Explore how to Monitor applications on big data clusters for more information. You can also check out additional samples at App Deploy Samples.

For more information about SQL Server Big Data Clusters, see What are SQL Server 2019 Big Data Clusters.

Share via