Scoring using Models Deployed into CAS over REST API: A Step-by-Step Guide
Data scientists build models to improve outcomes through better decision making. For their models to be effective, their models need to integrate with a business decisioning process. If our outcome is to reduce fraud losses, our model needs to be integrated into the real-time payments process to approve transactions as they appear. But if our outcome is to increase clicks from a personalized weekly email blast, our model needs to run once a week against all email recipients. To accommodate varying analytics needs, SAS Model Manager can deploy models into both batch and real-time destinations. In my previous article, we discussed how to score data over REST API using models deployed into the SAS Micro Analytics Service (MAS). In this article, we will focus on using SAS Cloud Analytic Services (CAS) for batch.
SAS Cloud Analytic Services provides the run-time environment for data management and analytics on SAS Viya. Thus, you will hear CAS referenced as a place to store data, but also as an analytical engine. CAS operates in-memory to provide the best performance for big data.
CAS requires that users communicate via a session. To leverage CAS programmatically, users must first start a session. Sessions are used for authentication, fault isolation, efficient scoping of resources, and resource tracking.
Deploying and scoring a model using CAS takes just a few steps. In fact, if you are using SAS Model Manager, you can score data using CAS via a Scoring Test in just a few clicks. From the Scoring tab of a Model Manger project, click New Test. Next, give your test a name and select the model, input table, and output library before clicking Run.
When your test completes, a green check mark will appear under the Status column. Next, click the table icon under the Results column and then you can explore the results metadata, output data, code, and log.
You can also publish and run a model programmatically using PROC CAS or SWAT. Regardless, some teams prefer to leverage the APIs to build an automated process. In this article, I will walk through the steps using the APIs for scoring.
Step 1: Create the CAS destination
Unlike the MAS destination, the CAS destination is not available out-of-the-box. But that is not a problem! An admin can configure the destination in just a few steps from the SAS Viya CLI or from Environment Manager.
From Environment Manager in SAS Viya, first click Publishing Destinations. Then click the folder icon in the upper-right corner to create a new destination. Select the type as CAS, give the destination a name, select the CAS server, select the CAS library, and finally give the model table a name before clicking save.
Step 2: Publish the model to CAS
Now that we have configured our destination, we are ready to publish our model. We can deploy a SAS, Python, or R model into CAS. First, select your model(s) and hit the Publish button. From the Publish Models dialogue, select the CAS destination. Give your published model a memorable name before clicking the Publish button. In just a few seconds, we are ready to start scoring data over REST API using our model!
Step 3: Prepare to call REST API
REST APIs are a standard for communication between applications. Given the popularity of REST APIs, users have a variety of ways to call REST APIs. REST APIs can be called using tools like Postman or Insomnia, via cURL, using the requests package in Python, and many other methods. This allows users to call REST APIS using the method that is easiest for their skill sets or best fits their process needs.
I personally prefer programming in Python, but the following examples can easily be adapted to other methods. But just a note for our Python and R developers: instead of calling the APIs directly, you can also call CAS actions using the SWAT package. If you would like to see an article about scoring using models deployed to CAS over SWAT, please let me know in the comments! Otherwise, to call APIs in Python, I need to import two packages: requests and json.
import requests
import json
Regardless of the method you use to call the REST APIs, you will need three things: the URL of your SAS Viya environment, your username, and your password. The following block prompts a user to enter this information in Python:
#Package to hide passwords
import getpass
host = input("Viya URL: ")
username = input("Username: ")
password = getpass.getpass("Password: ")
Step 4: Get Access Token
An access token allows us to make the REST API calls to SAS Viya. We can reuse our access token, but it will expire after a set time passes. To use your token longer, you can refresh your token or increase the timeout before the token expires.
This is a POST request to the /SASLogon/oauth/token endpoints with your username and password in the body of the request.
url = f"{host}/SASLogon/oauth/token"
authBody = 'grant_type=password&username=%s&password=%s' %(username, password)
headersAuth={'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded'}
r = requests.request('POST', url, data= authBody, headers=headersAuth, auth=('sas.ec', ''))
token = r.json()['access_token']
Alternatively, there are a few other approaches you can take to creating your access token, as highlighted in developer advocate Joe Furbee’s blog and Simon Edward’s article.
Step 5: Start Session
To interact with CAS, we need to start a session. We can start a session by making a POST request to the /cas/sessions endpoint with our authorization token within the headers. We will need to save the session ID to make our future requests.
headers = {'Authorization': 'Bearer ' + token}
url = f"{host}cas-shared-default-http/cas/sessions"
r = requests.request('POST', url, headers = headers)
session = r.json()['session']
Step 6: Load Data
Unlike MAS scoring where we pass a row of data, CAS scoring operates on a table in CAS. There are several methods for loading data into CAS. Using the Data Explorer on SAS Viya, under Manage Data in the main menu, we can build connections to a database or import a local file in just a few steps. We can also load data programmatically. For example, Peter Styliadis’s blog details one way to load csv files into CAS from Python.
Step 7: Make Scoring Rest Call
Using the method outlined by Joe Furbee in this blog, we can translate CASL code into REST APIs. I leveraged this method for the runModelLocal action.
Before we can score our data, we need to specify the input data, the model name and location, and where we want the data to end up. The following block prompts a user to enter this information in Python:
inlib = input("Input CAS Library: ")
intable = input("Input CAS Table: ")
modelname = input("Model Name: ")
inmodel = input("Model CAS Library: ")
modeltable = input("Model CAS Table: ")
outlib = input("Output CAS Library: ")
outtable = input("Output CAS Table: ")
Now we have everything we need to score the data using the model published into CAS. Our payload will include our data and model information, which will we pass as a POST request to the /cas/sessions/sessionID/actions/modelPublishing.runModelLocal endpoint, where we replace sessionID with the session ID we generated earlier.
headers = {'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json'}
payload = {"inTable":{"caslib":inlib, "name":intable},
"modelName":modelname,
"modelTable":{"caslib":inmodel,"name":modeltable},
"outTable":{"caslib":outlib,"name":outtable}}
url =f"{host}cas-shared-default-http/cas/sessions/{session}/actions/modelPublishing.runModelLocal"
r = requests.request('POST', url, json = payload, headers = headers)
r.json()
Step 8: Promote Data or Pull Data
Our table was scored within our CAS session and as such, is not available outside our session. But, with one more call we can promote our table so it is available globally, even after our session is gone. To promote our table, we will make a POST request to the /cas/sessions/sessionID/actions/table.promote endpoint. We will also need a payload compiling the name and library of our table as well as a target location for our table after promotion.
headers = {'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json'}
payload = {"caslib":outlib,
"name":outtable,
"target":outtable,
"targetLib":outlib}
url =f"{host}cas-shared-default-http/cas/sessions/{session}/actions/table.promote"
r = requests.request('POST', url, json = payload, headers = headers)
r.json()
Conversely, we may not want our table promoted globally. We may just want to view our table now. We can pull data from CAS using the fetch action. To fetch a table from CAS, we will make a POST request to the /cas/sessions/sessionID/actions/table.fetch endpoint. In our payload, we will specify which table we want to pull as well as how many rows we want to pull.
headers = {'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json'}
payload = {"maxRows":10,
"table":{"caslib":outlib,"name":outtable}}
url =f"{host}cas-shared-default-http/cas/sessions/{session}/actions/table.fetch"
r = requests.request('POST', url, json = payload, headers = headers)
If we are pulling this data via Python, we can save it as a data frame using pandas.
import pandas as pd
columns = []
for x in (r.json()['results']['Fetch']['schema']):
columns.append(x['name'])
df = pd.DataFrame(r.json()['results']['Fetch']['rows'], columns = columns)
df
Step 9: Close session
Our session will expire after a set amount of time passes, but we can be good stewards of our resources by closing our session once we are done. We can close our session by making a DELETE request to the /cas/sessions/sessionID endpoint, where we replace sessionID with the session ID we generated earlier.
headers = {'Authorization': 'Bearer ' + token}
url = f"{host}cas-shared-default-http/cas/sessions/{session}"
r = requests.request('DELETE', url, headers = headers)
r
A 200 response indicates that our session was closed successfully.
And now you are ready to score using models deployed into CAS over REST API! What other publishing destinations do you want to learn more about? Let me know in the comments below! Do any CAS power-users have tips and best practices to share? Add them below as well!
