Share via

Use Microsoft Graph Purview APIs

Call flow for apps with user interaction

There are two primary steps your app needs to take to process prompts and responses with Microsoft Purview. Compute protection scopes and Process content.

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 10 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.

Adding app-only permissions to your service app

Follow the steps to Grant an appRoleAssignment to a service principal to add app-only permissions to your service app. The app-only permissions your service may need are:

Permission Permission ID
ProtectionScopes.Compute.All e5a76501-dbb0-492c-ab55-5d09e8837263
Content.Process.All 5ad511bf-571c-4ef6-8c3c-85b94b85df98
ContentActivity.Read 368425e7-6954-4f5a-9d92-90b75bd580c9
ContentActivity.Write 2932e07a-3c29-44e4-bb36-6d0fc176387f
SensitivityLabel.Evaluate.All 986fa56a-6680-4aac-af09-4d1765376739
SensitivityLabels.Read.All e46a01e9-b2cf-4d89-8424-bcdc6dd445ab

Next steps