Skip to content

Commit 2e59dd1

Browse files
jovinson-msjosiahvinson
jovinson-ms
and
josiahvinson
authored
Pulling in SDK changes from Java (Azure#49525)
* Pulling in SDK changes from Java * Samples and Public API * Updating TypeSpec location, sample code, and documentation. * README fix * README link fix * fix generated sample --------- Co-authored-by: Josiah Vinson <[email protected]>
1 parent d5743a9 commit 2e59dd1

35 files changed

+461
-480
lines changed

‎sdk/healthdataaiservices/Azure.Health.Deidentification/CHANGELOG.md‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,21 @@
1111

1212
### Breaking Changes
1313

14-
- Changed `outputPrefix` behavior from including `jobName` to prefix replacement method
15-
- Changed `Path` field to `Location` in `SourceStorageLocation` and `TargetStorageLocation`
16-
- Deprecated `DocumentDataType`
17-
- Deprecated `Path` and `Location` from `TaggerResult` model
14+
- Changed method names in `DeidentificationClient` to match functionality:
15+
- Changed the `Deidentify*` method names to `DeidentifyText*`.
16+
- Changed the `CreateJob*` method names to `DeidentifyDocuments*`.
17+
- Renamed the property `DeidentificationContent.Operation` to `OperationType`.
18+
- Deprecated `DocumentDataType`.
19+
- Changed the model `DeidentificationDocumentDetails`:
20+
- Renamed `Input` to `InputLocation`.
21+
- Renamed `Output` to `OutputLocation`.
22+
- Changed the model `DeidentificationJob`
23+
- Renamed `Name` to `JobName`.
24+
- Renamed `Operation` to `OperationType`.
25+
- Renamed the model `OperationState` to `OperationStatus`.
26+
- Changed `Path` field to `Location` in `SourceStorageLocation` and `TargetStorageLocation`.
27+
- Changed handling of `TargetStorageLocation.Prefix` to only include the provided value. Previously, the generated document locations would include the `DeidentificationJob.JobName` by default.
28+
- Deprecated `Path` and `Location` from `TaggerResult` model.
1829

1930
## 1.0.0-beta.1 (2024-08-15)
2031

‎sdk/healthdataaiservices/Azure.Health.Deidentification/README.md‎

Lines changed: 81 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,94 @@
1-
# Azure Health.Deidentification client library for .NET
1+
# Azure Health Data Services de-identification service client library for .NET
2+
[![Nuget](https://img.shields.io/nuget/v/Azure.Health.Deidentification.svg?style=flat-square)][deid_nuget]
23

3-
Azure.Health.Deidentification is a managed service that enables users to tag, redact, or surrogate health data.
4+
This package contains a client library for the de-identification service in Azure Health Data Services which
5+
enables users to tag, redact, or surrogate health data containing Protected Health Information (PHI).
6+
For more on service functionality and important usage considerations, see [the de-identification service overview][product_documentation].
47

5-
6-
<!-- TODO Add operation links once docs are generated -->
7-
8-
[Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/healthdataaiservices/Azure.Health.Deidentification/src) | [Package (NuGet)](https://www.nuget.org/packages) | [API reference documentation](https://azure.github.io/azure-sdk-for-net) | [Product documentation](https://learn.microsoft.com/azure) | [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/healthdataaiservices/Azure.Health.Deidentification/samples)
8+
[Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/healthdataaiservices/Azure.Health.Deidentification/src) | [Package (NuGet)][deid_nuget] | [API reference documentation][docs] | [Product documentation][product_documentation] | [Samples][samples]
99

1010
## Getting started
1111

12+
### Prerequisites
13+
14+
- Have an [Azure Subscription][azure_subscription].
15+
- [Deploy the de-identification service][deid_quickstart].
16+
- [Configure Azure role-based access control (RBAC)][deid_rbac] for the operations you will perform.
1217

1318
### Install the package
1419

15-
Install the client library for .NET with [NuGet](https://www.nuget.org/ ):
20+
Install the .NET client library [NuGet package][deid_nuget]:
1621

1722
```dotnetcli
1823
dotnet add package Azure.Health.Deidentification
1924
```
2025

21-
### Prerequisites
22-
23-
> You must have an `Azure subscription` and `Deid Service`.
24-
2526
### Authenticate the client
2627

27-
Pull `ServiceUrl` from your created Deidentification Service.
28-
29-
![Service Url Location](docs/images/ServiceUrl_Location.png)
28+
You will need a **service URL** to instantiate a client. You can find the service URL for a particular resource
29+
in the [Azure portal][azure_portal]: ![Service Url Location](docs/images/ServiceUrl_Location.png)
3030

31-
Basic code snippet to create your Deidentification Client and Deidentify a string.
32-
33-
```cs
34-
const string serviceEndpoint = "https://example.api.cac001.deid.azure.com";
35-
TokenCredential credential = new DefaultAzureCredential();
36-
37-
DeidentificationClient client = new(
38-
new Uri(serviceEndpoint),
39-
credential,
40-
new DeidentificationClientOptions()
41-
);
31+
You can also find the service URL with [Azure CLI][azure_cli]:
32+
```bash
33+
# Get the service URL for the resource
34+
az deidservice show --name "<resource-name>" --resource-group "<resource-group-name>" --query "properties.serviceUrl"
35+
```
4236

43-
DeidentificationContent content = new("Hello, John!");
37+
The [Azure Identity][azure_identity] package provides the default implementation for authenticating the client.
38+
You can use `DefaultAzureCredential` to automatically find the best credential to use at runtime.
4439

45-
Response<DeidentificationResult> result = client.DeidentifyText(content);
46-
string outputString = result.Value.OutputText;
47-
Console.WriteLine(outputString); // Hello, Tom!
40+
```C# Snippet:AzHealthDeidSample1_DemonstrateCredential
41+
const string serviceEndpoint = "https://example.api.cac001.deid.azure.com";
42+
TokenCredential credential = new DefaultAzureCredential();
43+
```
44+
```C# Snippet:AzHealthDeidSample1_HelloWorld
45+
DeidentificationClient client = new(
46+
new Uri(serviceEndpoint),
47+
credential,
48+
new DeidentificationClientOptions()
49+
);
4850
```
4951

5052
## Key concepts
5153

52-
**Operation Modes**
53-
- Tag: Will return a structure of offset and length with the PHI category of the related text spans.
54-
- Redact: Will return output text with placeholder stubbed text. ex. `[name]`
55-
- Surrogate: Will return output text with synthetic replacements.
56-
- `My name is John Smith`
57-
- `My name is Tom Jones`
54+
### Operation Types
55+
Given an input text, the de-identification service can perform three main operations:
56+
- `Tag` returns the category and location within the text of detected PHI entities.
57+
- `Redact` returns output text where detected PHI entities are replaced with placeholder text. For example `John` replaced with `[name]`.
58+
- `Surrogate` returns output text where detected PHI entities are replaced with realistic replacement values. For example, `My name is John Smith` could become `My name is Tom Jones`.
5859

59-
**Job Integration with Azure Storage**
60-
Instead of sending text, you can send an Azure Storage Location to the service. We will asynchronously
61-
process the list of files and output the deidentified files to a location of your choice.
60+
For more information about customizing the redaction format, see [Tutorial: Use a custom redaction format with the de-identification service][deid_redaction_format].
6261

63-
Limitations:
64-
- Maximum file count per job: 1000 documents
65-
- Maximum file size per file: 2 MB
62+
### De-identification Methods
63+
There are two methods of interacting with the de-identification service. You can send text directly, or you can create jobs
64+
to de-identify documents in Azure Storage.
6665

67-
**Redaction Formatting**
66+
You can de-identify text directly using the `DeidentificationClient`:
67+
```C# Snippet:AzHealthDeidSample1_CreateRequest
68+
DeidentificationContent content = new("Hello, John!");
6869

69-
[Redaction formatting guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/healthdataaiservices/Azure.Health.Deidentification/docs/HowTo-RedactionFormatting.md)
70+
Response<DeidentificationResult> result = client.DeidentifyText(content);
71+
string outputString = result.Value.OutputText;
72+
Console.WriteLine(outputString); // Hello, Tom!
73+
```
74+
75+
To learn about prerequisites and configuration options for de-identifying documents in Azure Storage, see [Tutorial: Configure Azure Storage to de-identify documents][deid_configure_storage].
76+
Once you have configured your storage account, you can create a job to de-identify documents in a container.
77+
```C# Snippet:AzHealthDeidSample2_CreateJob
78+
DeidentificationJob job = new()
79+
{
80+
SourceLocation = new SourceStorageLocation(new Uri(storageAccountUrl), "folder1/"),
81+
TargetLocation = new TargetStorageLocation(new Uri(storageAccountUrl), "output_folder1/"),
82+
OperationType = DeidentificationOperationType.Redact,
83+
};
84+
85+
job = client.DeidentifyDocuments(WaitUntil.Started, "my-job-1", job).Value;
86+
Console.WriteLine($"Job status: {job.Status}"); // Job status: NotStarted
87+
```
7088

7189
### Thread safety
7290

73-
We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
91+
All client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
7492

7593
### Additional concepts
7694
<!-- CLIENT COMMON BAR -->
@@ -85,18 +103,17 @@ We guarantee that all client instance methods are thread-safe and independent of
85103

86104
## Examples
87105

88-
You can familiarize yourself with different APIs using [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/healthdataaiservices/Azure.Health.Deidentification/samples).
106+
For sample code snippets illustrating common patterns used in the de-identification service, see the [samples][samples].
89107

90108
## Next steps
91109

92-
- Find a bug, or have feedback? Raise an issue with "Health Deidentification" Label.
93-
110+
- Find a bug, or have feedback? Raise an issue with the [Health Deidentification][github_issue_label] label.
94111

95112
## Troubleshooting
96113

97-
- **Unabled to Access Source or Target Storage**
98-
- Ensure you create your deid service with a system assigned managed identity
99-
- Ensure your storage account has given permissions to that managed identity
114+
- **Unable to Access Source or Target Storage**
115+
- Ensure you [assign a managed identity][deid_managed_identity] to your de-identification service
116+
- Ensure you [assign appropriate permissions][deid_rbac] to the managed identity to access the storage account
100117

101118
## Contributing
102119

@@ -117,5 +134,17 @@ additional questions or comments.
117134

118135
<!-- LINKS -->
119136
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
120-
[style-guide-msft]: https://learn.microsoft.com/style-guide/capitalization
121-
[style-guide-cloud]: https://aka.ms/azsdk/cloud-style-guide
137+
[product_documentation]: https://learn.microsoft.com/azure/healthcare-apis/deidentification/
138+
[docs]: https://learn.microsoft.com/dotnet/api/azure.health.deidentification
139+
[deid_nuget]: https://www.nuget.org/packages/Azure.Health.Deidentification
140+
[deid_redaction_format]: https://learn.microsoft.com/azure/healthcare-apis/deidentification/redaction-format
141+
[azure_subscription]: https://azure.microsoft.com/free/
142+
[deid_quickstart]: https://learn.microsoft.com/azure/healthcare-apis/deidentification/quickstart
143+
[deid_rbac]: https://learn.microsoft.com/azure/healthcare-apis/deidentification/manage-access-rbac
144+
[deid_managed_identity]: https://learn.microsoft.com/azure/healthcare-apis/deidentification/managed-identities
145+
[deid_configure_storage]: https://learn.microsoft.com/azure/healthcare-apis/deidentification/configure-storage
146+
[azure_identity]: https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme
147+
[azure_cli]: https://learn.microsoft.com/cli/azure/healthcareapis/deidservice?view=azure-cli-latest
148+
[azure_portal]: https://ms.portal.azure.com
149+
[github_issue_label]: https://github.com/Azure/azure-sdk-for-net/labels/Health%20Deidentification
150+
[samples]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/healthdataaiservices/Azure.Health.Deidentification/samples/README.md

0 commit comments

Comments
 (0)