|
| 1 | +# Azure Deidentification client library for Java |
| 2 | + |
| 3 | +Azure Deidentification client library for Java. |
| 4 | + |
| 5 | +This package contains Microsoft Azure Deidentification client library which is a managed service that enables users to tag, redact, or surrogate health data. |
| 6 | + |
| 7 | +## Documentation |
| 8 | + |
| 9 | +Various documentation is available to help you get started |
| 10 | + |
| 11 | +- [API reference documentation][docs] |
| 12 | +- [Product documentation][product_documentation] |
| 13 | + |
| 14 | +## Getting started |
| 15 | + |
| 16 | +### Prerequisites |
| 17 | + |
| 18 | +- [Java Development Kit (JDK)][jdk] with version 8 or above |
| 19 | +- [Azure Subscription][azure_subscription] |
| 20 | + |
| 21 | +### Adding the package to your product |
| 22 | + |
| 23 | +[//]: # ({x-version-update-start;com.azure:azure-health-deidentification;current}) |
| 24 | +```xml |
| 25 | +<dependency> |
| 26 | + <groupId>com.azure</groupId> |
| 27 | + <artifactId>azure-health-deidentification</artifactId> |
| 28 | + <version>1.0.0-beta.1</version> |
| 29 | +</dependency> |
| 30 | +``` |
| 31 | +[//]: # ({x-version-update-end}) |
| 32 | + |
| 33 | +### Authentication |
| 34 | + |
| 35 | +[Azure Identity][azure_identity] package provides the default implementation for authenticating the client. |
| 36 | + |
| 37 | +## Key concepts |
| 38 | +### Operation Modes: |
| 39 | + |
| 40 | +- Tag: Will return a structure of offset and length with the PHI category of the related text spans. |
| 41 | +- Redact: Will return output text with placeholder stubbed text. ex. `[name]` |
| 42 | +- Surrogate: Will return output text with synthetic replacements. |
| 43 | + - `My name is John Smith` |
| 44 | + - `My name is Tom Jones` |
| 45 | + |
| 46 | +## Examples |
| 47 | + |
| 48 | +The following sections provide several code snippets covering some of the most common Azure Deidentification client use cases, including: |
| 49 | + |
| 50 | +- [Create a `DeidentificationClient`](#create-a-deidentificationclient) |
| 51 | +- [Calling deidentification endpoint](#calling-deidentification-endpoint) |
| 52 | +- [Creating deidentification Job](#creating-deidentification-job) |
| 53 | +- [Process deidentification Job](#process-deidentification-job) |
| 54 | +- [List deidentification Jobs](#list-deidentification-jobs) |
| 55 | +- [List completed files](#list-completed-files) |
| 56 | + |
| 57 | +### Create a `DeidentificationClient` |
| 58 | + |
| 59 | +Create a `DeidentificationClient` using the `DEID_SERVICE_ENDPOINT` environment variable. |
| 60 | + |
| 61 | +```java com.azure.health.deidentification.readme |
| 62 | +DeidentificationClientBuilder deidentificationClientbuilder = new DeidentificationClientBuilder() |
| 63 | + .endpoint(Configuration.getGlobalConfiguration().get("DEID_SERVICE_ENDPOINT", "endpoint")) |
| 64 | + .httpClient(HttpClient.createDefault()) |
| 65 | + .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BASIC)); |
| 66 | + |
| 67 | +DeidentificationClient deidentificationClient = deidentificationClientbuilder.buildClient(); |
| 68 | +``` |
| 69 | + |
| 70 | +### Calling `Deidentification` endpoint |
| 71 | + |
| 72 | +Calling the realtime endpoint with an input. |
| 73 | + |
| 74 | +```java com.azure.health.deidentification.sync.helloworld |
| 75 | +String inputText = "Hello, my name is John Smith."; |
| 76 | + |
| 77 | +DeidentificationContent content = new DeidentificationContent(inputText); |
| 78 | + |
| 79 | +DeidentificationResult result = deidentificationClient.deidentify(content); |
| 80 | + |
| 81 | +System.out.println("Deidentified output: " + result.getOutputText()); |
| 82 | +// Deidentified output: Hello, my name is Harley Billiard. |
| 83 | +``` |
| 84 | +### Creating Deidentification Job |
| 85 | + |
| 86 | +Creating a Deidentification Job using `STORAGE_ACCOUNT_NAME` and `STORAGE_CONTAINER_NAME` environment variables. |
| 87 | + |
| 88 | +```java com.azure.health.deidentification.sync.createjob.create |
| 89 | +String storageLocation = "https://" + Configuration.getGlobalConfiguration().get("STORAGE_ACCOUNT_NAME") + ".blob.core.windows.net/" + Configuration.getGlobalConfiguration().get("STORAGE_CONTAINER_NAME"); |
| 90 | +String jobName = "MyJob-" + Instant.now().toEpochMilli(); |
| 91 | +String outputFolder = "_output"; |
| 92 | +String inputPrefix = "example_patient_1"; |
| 93 | +SourceStorageLocation sourceStorageLocation = new SourceStorageLocation(storageLocation, inputPrefix); |
| 94 | + |
| 95 | +DeidentificationJob job = new DeidentificationJob(sourceStorageLocation, new TargetStorageLocation(storageLocation, outputFolder)); |
| 96 | +job.setOperation(OperationType.SURROGATE); |
| 97 | +job.setDataType(DocumentDataType.PLAINTEXT); |
| 98 | + |
| 99 | +``` |
| 100 | +### Process Deidentification Job |
| 101 | + |
| 102 | +Create and poll job until it is completed. |
| 103 | + |
| 104 | +```java com.azure.health.deidentification.sync.createjob.process |
| 105 | +DeidentificationJob result = deidentificationClient.beginCreateJob(jobName, job) |
| 106 | + .waitForCompletion() |
| 107 | + .getValue(); |
| 108 | +System.out.println(jobName + " - " + result.getStatus()); |
| 109 | +// MyJob-1719953889301 - Succeeded |
| 110 | +``` |
| 111 | + |
| 112 | +### List Deidentification Jobs |
| 113 | + |
| 114 | +List and process deidentification jobs |
| 115 | + |
| 116 | +```java com.azure.health.deidentification.sync.listjobs |
| 117 | +PagedIterable<DeidentificationJob> jobs = deidentificationClient.listJobs(); |
| 118 | +for (DeidentificationJob currentJob : jobs) { |
| 119 | + System.out.println(currentJob.getName() + " - " + currentJob.getStatus()); |
| 120 | + // MyJob-1719953889301 - Succeeded |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +### List completed files |
| 125 | + |
| 126 | +List the files which are completed by a job. |
| 127 | + |
| 128 | +```java com.azure.health.deidentification.sync.listcompletedfiles |
| 129 | +PagedIterable<DocumentDetails> reports = deidentificationClient.listJobDocuments(jobName); |
| 130 | + |
| 131 | +for (DocumentDetails currentFile : reports) { |
| 132 | + System.out.println(currentFile.getId() + " - " + currentFile.getOutput().getPath()); |
| 133 | + // c45dcd5e-e3ce-4ff2-80b6-a8bbeb47f878 - _output/MyJob-1719954393623/example_patient_1/visit_summary.txt |
| 134 | + // e55a1aa2-8eba-4515-b070-1fd3d005008b - _output/MyJob-1719954393623/example_patient_1/doctor_dictation.txt |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | + |
| 139 | + |
| 140 | +## Troubleshooting |
| 141 | + |
| 142 | +## Next steps |
| 143 | + |
| 144 | +## Contributing |
| 145 | + |
| 146 | +For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-java/blob/main/CONTRIBUTING.md). |
| 147 | + |
| 148 | +1. Fork it |
| 149 | +1. Create your feature branch (`git checkout -b my-new-feature`) |
| 150 | +1. Commit your changes (`git commit -am 'Add some feature'`) |
| 151 | +1. Push to the branch (`git push origin my-new-feature`) |
| 152 | +1. Create new Pull Request |
| 153 | + |
| 154 | +<!-- LINKS --> |
| 155 | +[product_documentation]: https://azure.microsoft.com/services/ |
| 156 | +[docs]: https://azure.github.io/azure-sdk-for-java/ |
| 157 | +[jdk]: https://learn.microsoft.com/azure/developer/java/fundamentals/ |
| 158 | +[azure_subscription]: https://azure.microsoft.com/free/ |
| 159 | +[azure_identity]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/identity/azure-identity |
| 160 | + |
| 161 | + |
0 commit comments