Edit

Quickstart: Azure Health De-identification client library for .NET

Get started with the Azure Health De-identification client library for .NET to de-identify your health data. Follow these steps to install the package and try out example code for basic tasks.

API reference documentation | Library source code | Package (NuGet) | More Samples on GitHub

Prerequisites

Set up the de-identification environment

Create a de-identification service

A de-identification service provides you with an endpoint URL. You can use this endpoint URL as a REST API or with an SDK.

  1. Install Azure CLI.

  2. Create a de-identification service resource.

    REGION="<Region>"
RESOURCE_GROUP_NAME="<ResourceGroupName>"
DEID_SERVICE_NAME="<NewDeidServiceName>"
az resource create -g $RESOURCE_GROUP_NAME -n $DEID_SERVICE_NAME --resource-type microsoft.healthdataaiservices/deidservices --is-full-object -p "{\"identity\":{\"type\":\"SystemAssigned\"},\"properties\":{},\"location\":\"$REGION\"}"

Assign RBAC roles to the de-identification service

Assign a role to your de-identification service so you have permissions to perform the actions in this quickstart.

Because you're using real-time and job endpoints, assign the DeID Data Owner roles.

To learn how to assign this role to your de-identification service, see Manage access to the de-identification service with Azure role-based access control (RBAC) in Azure Health Data Services.

Create an Azure Storage account

  1. Install Azure CLI.

  2. Create an Azure Storage Account

    STORAGE_ACCOUNT_NAME="<NewStorageAccountName>"
az storage account create --name $STORAGE_ACCOUNT_NAME --resource-group $RESOURCE_GROUP_NAME --location $REGION

Authorize de-identification service on the Azure Storage account

Give the de-identification service access to your storage account.

STORAGE_ACCOUNT_ID=$(az storage account show --name $STORAGE_ACCOUNT_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv)
DEID_SERVICE_PRINCIPAL_ID=$(az resource show -n $DEID_SERVICE_NAME -g $RESOURCE_GROUP_NAME  --resource-type microsoft.healthdataaiservices/deidservices --query identity.principalId --output tsv)
az role assignment create --assignee $DEID_SERVICE_PRINCIPAL_ID --role "Storage Blob Data Contributor" --scope $STORAGE_ACCOUNT_ID

Install the package

You can get the client library through NuGet as the Azure.Health.Deidentification package.

  1. Install the package.

    dotnet add package Azure.Health.Deidentification

  2. Also, install the Azure Identity package if you didn't already install it.

    dotnet add package Azure.Identity

Object model

Code examples

Create a de-identification client

Before you can create the client, you need to find your de-identification service endpoint URL.

Use the Azure CLI to find the endpoint URL.

az resource show -n $DEID_SERVICE_NAME -g $RESOURCE_GROUP_NAME  --resource-type microsoft.healthdataaiservices/deidservices --query properties.serviceUrl --output tsv

Then, create the client by using that value.

using Azure.Identity;
using Azure.Health.Deidentification;

string serviceEndpoint = "https://example123.api.deid.azure.com";

DeidentificationClient client = new(
    new Uri(serviceEndpoint),
    new DefaultAzureCredential()
);

De-identify a string

Use this function to de-identify any string you have in memory.

DeidentificationContent content = new("SSN: 123-04-5678");
DeidentificationResult result = await client.DeidentifyAsync(content);

Tag a string

You can tag a string the same way you de-identify a string. Change the OperationType to tag a string.

DeidentificationContent content = new("SSN: 123-04-5678");
content.Operation = OperationType.Tag;

DeidentificationResult result = await client.DeidentifyAsync(content);

Create a de-identification job

This function de-identifies all files that have a specific prefix within an Azure Blob Storage Account.

To create the job, you need the URL to the blob endpoint of the Azure Storage Account.

az resource show -n $STORAGE_ACCOUNT_NAME -g $RESOURCE_GROUP_NAME  --resource-type Microsoft.Storage/storageAccounts --query properties.primaryEndpoints.blob --output tsv

Now you can create the job. This example uses folder1/ as the prefix. The job de-identifies any document that matches this prefix and writes the de-identified version with the output_files/ prefix.

using Azure;

Uri storageAccountContainerUri = new("https://exampleStorageAccount.blob.core.windows.net/containerName");

DeidentificationJob job = new(
    new SourceStorageLocation(storageAccountContainerUri, "folder1/"),
    new TargetStorageLocation(storageAccountContainerUri, "output_files/")
);

job = client.CreateJob(WaitUntil.Started, "my-job-1", job).Value;

Get the status of a de-identification job

After you create a job, you can view the status and other details of the job.

DeidentificationJob job = client.GetJob("my-job-1").Value;

Run the code

After you update your code in your project, run it by using:

dotnet run

Clean up resources

Delete de-identification service

az resource delete -n $DEID_SERVICE_NAME -g $RESOURCE_GROUP_NAME  --resource-type microsoft.healthdataaiservices/deidservices

Delete Azure Storage account

az resource show -n $STORAGE_ACCOUNT_NAME -g $RESOURCE_GROUP_NAME  --resource-type Microsoft.Storage/storageAccounts

Delete role assignment

az role assignment delete --assignee $DEID_SERVICE_PRINCIPAL_ID --role "Storage Blob Data Contributor" --scope $STORAGE_ACCOUNT_ID

Troubleshooting

Unable to access source or target storage

Ensure you have the necessary permissions, and that the Managed Identity for the de-identification service is set up properly.

See Authorize de-identification service on the Azure Storage account.

Job failed with status PartialFailed

Use the GetJobDocuments function on the DeidentificationClient to view per file error messages.

See Sample.

Next steps

In this quickstart, you learned:

  • How to create a de-identification service and assign a role on a storage account.
  • How to create a de-identification client.
  • How to de-identify strings and create jobs on documents within a storage account.

View source code and .NET Client Library README

  • Last updated on