Share via

Use Microsoft Purview APIs in the Microsoft Graph

To safeguard your Enterprise AI apps, your apps need to perform two core calls to Microsoft Purview APIs to handle user prompts and model responses:

  1. Compute protection scopes: determines which user activities (for example, uploadText, downloadText) require policy evaluation.
  2. Process content: sends a content activity for policy evaluation and returns any policy actions your app must enforce (for example, block or modify the activity).

The sections below describe the call sequence and how to implement each step in your app.

For a detailed walkthrough of a demo app that makes these API calls, see the Microsoft Reactor video.

Compute protection scopes

The first step is to compute the protection scope state for the user by calling Compute protection scopes. This call should occur shortly after the user authenticates to your application. Compute protection scopes will return a collection of policyUserScopes.

  • If the collection is not empty your app must call Process content for some or all user activities. The user activities your app will need to track are uploadText (a text prompt from the user), uploadFile (as part of a prompt from the user), downloadText (a text response from the AI), and downloadFile (as part of a response from the AI). To build the protection scope state for the user start with a state for the user for each of these activities that indicates not to call Process content. Step through each scope in the collection returned from Compute protection scopes. For each activity in the policyUserScopes set the user's protection scope state to call Process content. If the scope has an executionMode of “evaluateInline” note that the call to Process content must block on the return before proceeding with the activity. Once the entries in the collection are all processed, your app will know which activities require a call to Process content and if your app must block on the return before continuing the activity.
  • If the collection is empty, your app could log data from processed content in a structured format to ensure audit compliance, track user actions, and drive anomalous behavior detections by calling Content activity. Your app should provide a settings option that allows customers to set your app to call Content activity when there are no scopes in the collection returned by policyUserScopes. With an empty policyUserScopes collection, your app should periodically refresh the user's protection scope state by calling Compute protection scopes. This is required to respond the any policy changes in the tenant. The suggested interval is approximately 30 minutes.

Compute protection scopes will also return an “ETag” header that represents the state of the protection scopes for the user. Your app should cache this value for the user.

Process content

The next step is to call Process content. Your app will use the user's protection scope state that your app computed. For each activity, check the user’s protection scope state and call Process content as appropriate. As part of this call, provide the “ETag” value that your app cached from the call to Compute protection scopes for the user as an “If-None-Match” header. Process content will return a Process content response.

If the policyActions collection in the Process content response is empty, continue with the activity. If the policyActions collection is not empty, step through each action and take the appropriate action. For example the action could be “restrictAccess” and your app would block the action.
The Process content response also contains the protectionScopeState property. If this is “modified”, your app must refresh its protection scope cache for the user since the policies in the tenant have changed.

Next steps