[TA] Analyze Batch Actions implementation updates (Azure#18898)

Analyze Batch Actions implementation updates based on the ArchiBoard and v-team internal feedbacks

Author: mssfang

eng/code-quality-reports/src/main/resources/spotbugs/spotbugs-exclude.xml

@@ -1358,9 +1358,9 @@
 
   <!-- TextAnalyticsException fields re serializable -->
   <Match>
-    <Class name="com.azure.ai.textanalytics.models.TextAnalyticsException"/>
-    <Field name="errorInformationList"/>
-    <Bug pattern="SE_BAD_FIELD"/>
+    <Class name="com.azure.ai.textanalytics.models.TextAnalyticsException" />
+    <Field name="errors" />
+    <Bug pattern="SE_BAD_FIELD" />
   </Match>
 
   <!-- Exception is required to catch, ref: code comment in the OrderbyRowComparer::compare() method  -->

sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Release History
 ## 5.1.0-beta.4 (Unreleased)
+### Breaking changes
+#### Analyze multiple actions
+- Replace API `PollerFlux<TextAnalyticsOperationResult, PagedFlux<AnalyzeTasksResult>> beginAnalyzeTasks(
+  Iterable<TextDocumentInput> documents, AnalyzeTasksOptions options)` to 
+  `PollerFlux<AnalyzeBatchActionsOperationDetail, PagedFlux<AnalyzeBatchActionsResult>>
+  beginAnalyzeBatchActions(Iterable<TextDocumentInput> documents, TextAnalyticsActions actions, 
+  AnalyzeBatchActionsOptions options)`. 
+- New overload API, `PollerFlux<AnalyzeBatchActionsOperationDetail, PagedFlux<AnalyzeBatchActionsResult>>
+  beginAnalyzeBatchActions(Iterable<String> documents, TextAnalyticsActions actions, String language, 
+  AnalyzeBatchActionsOptions options)`
+- New class `ExtractKeyPhrasesActionResult`, `RecognizeEntitiesActionResult`, `RecognizePiiEntitiesActionResult`,
+  `TextAnalyticsActions`, `TextAnalyticsActionResult`
+- Removed `EntitiesTask`, `KeyPhrasesTask`, `PiiTask`, `TextAnalyticsErrorInformation`
+- Renamed
+  `AnalyzeTasksOptions` to `AnalyzeBatchActionsOptions`,
+  `AnalyzeTasksResult` to `AnalyzeBatchActionsResult`,
+  `EntitiesTaskParameters` to `RecognizeEntitiesOptions`
+  `KeyPhrasesTaskParameters` to `ExtractKeyPhrasesOptions`,
+  `PiiTaskParameters` to `RecognizePiiEntityOptions`,
+  `PiiEntityDomainType` to `PiiEntitiesDomainType`,
+  `RecognizePiiEntityOptions` to `RecognizePiiEntitiesOptions`,
+  `TextAnalyticsOperationResult` to `AnalyzeBatchActionsOperationDetail`,
 
 ## 5.0.2 (2021-01-14)
 ### Dependency updates

sdk/textanalytics/azure-ai-textanalytics/README.md

@@ -9,7 +9,7 @@ and includes six main functions:
 - Personally Identifiable Information Entity Recognition 
 - Linked Entity Recognition
 - Healthcare Recognition <sup>beta</sup>
-- Analyze Operation <sup>beta</sup>
+- Support Multiple Actions Per Document <sup>beta</sup>
 
 [Source code][source_code] | [Package (Maven)][package] | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][samples_readme]
 
@@ -315,7 +315,7 @@ Text Analytics for health is a containerized service that extracts and labels re
 unstructured texts such as doctor's notes, discharge summaries, clinical documents, and electronic health records.
 Currently, Azure Active Directory (AAD) is not supported in the Healthcare recognition feature. In order to use this 
 functionality, request to access public preview is required. For more information see [How to: Use Text Analytics for health][healthcare].
-<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L189-L232 -->
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L189-L225 -->
 ```java
 List<TextDocumentInput> documents = Arrays.asList(new TextDocumentInput("0",
     "RECORD #333582770390100 | MH | 85986313 | | 054351 | 2/14/2001 12:00:00 AM | "
@@ -353,29 +353,14 @@ syncPoller.getFinalResult().forEach(healthcareTaskResult ->
                         healthcareEntityLink.getDataSourceId(), healthcareEntityLink.getDataSource()));
             }
         });
-        healthcareEntities.getEntityRelations().forEach(
-            healthcareEntityRelation ->
-                System.out.printf("Is bidirectional: %s, target: %s, source: %s, relation type: %s.%n",
-                    healthcareEntityRelation.isBidirectional(),
-                    healthcareEntityRelation.getTargetLink(),
-                    healthcareEntityRelation.getSourceLink(),
-                    healthcareEntityRelation.getRelationType()));
     }));
 ```
-To cancel a long-running healthcare task,
-<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L239-L243 -->
-```java
-SyncPoller<TextAnalyticsOperationResult, Void> textAnalyticsOperationResultVoidSyncPoller
-    = textAnalyticsClient.beginCancelHealthcareTask("{healthcare_task_id}",
-    new RecognizeHealthcareEntityOptions().setPollInterval(Duration.ofSeconds(10)), Context.NONE);
-PollResponse<TextAnalyticsOperationResult> poll = textAnalyticsOperationResultVoidSyncPoller.poll();
-System.out.printf("Task status: %s.%n", poll.getStatus());
-```
-### Analyze multiple tasks
+
+### Analyze multiple actions
 The `Analyze` functionality allows to choose which of the supported Text Analytics features to execute in the same 
 set of documents. Currently, the supported features are: `entity recognition`, `key phrase extraction`, and 
 `Personally Identifiable Information (PII) recognition`. 
-<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L250-L290 -->
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L232-L280 -->
 ```java
 List<TextDocumentInput> documents = Arrays.asList(
     new TextDocumentInput("0",
@@ -387,34 +372,42 @@ List<TextDocumentInput> documents = Arrays.asList(
             + " www.contososteakhouse.com, call 312-555-0176 or send email to order@contososteakhouse.com! The"
             + " only complaint I have is the food didn't come fast enough. Overall I highly recommend it!")
 );
-SyncPoller<TextAnalyticsOperationResult, PagedIterable<AnalyzeTasksResult>> syncPoller =
-    textAnalyticsClient.beginAnalyzeTasks(documents,
-        new AnalyzeTasksOptions().setDisplayName("{tasks_display_name}")
-            .setKeyPhrasesExtractionTasks(Arrays.asList(new KeyPhrasesTask()))
-            .setPiiEntitiesRecognitionTasks(Arrays.asList(new PiiTask())),
+
+SyncPoller<AnalyzeBatchActionsOperationDetail, PagedIterable<AnalyzeBatchActionsResult>> syncPoller =
+    textAnalyticsClient.beginAnalyzeBatchActions(documents,
+        new TextAnalyticsActions().setDisplayName("{tasks_display_name}")
+            .setExtractKeyPhrasesOptions(new ExtractKeyPhrasesOptions())
+            .setRecognizePiiEntitiesOptions(new RecognizePiiEntitiesOptions()),
+        new AnalyzeBatchActionsOptions().setIncludeStatistics(false),
         Context.NONE);
 syncPoller.waitForCompletion();
-syncPoller.getFinalResult().forEach(analyzeJobState -> {
-    analyzeJobState.getKeyPhraseExtractionTasks().forEach(taskResult -> {
+syncPoller.getFinalResult().forEach(analyzeBatchActionsResult -> {
+    System.out.println("Key phrases extraction action results:");
+    analyzeBatchActionsResult.getExtractKeyPhrasesActionResults().forEach(actionResult -> {
         AtomicInteger counter = new AtomicInteger();
-        for (ExtractKeyPhraseResult extractKeyPhraseResult : taskResult) {
-            System.out.printf("%n%s%n", documents.get(counter.getAndIncrement()));
-            System.out.println("Extracted phrases:");
-            extractKeyPhraseResult.getKeyPhrases()
-                .forEach(keyPhrases -> System.out.printf("\t%s.%n", keyPhrases));
+        if (!actionResult.isError()) {
+            for (ExtractKeyPhraseResult extractKeyPhraseResult : actionResult.getResult()) {
+                System.out.printf("%n%s%n", documents.get(counter.getAndIncrement()));
+                System.out.println("Extracted phrases:");
+                extractKeyPhraseResult.getKeyPhrases()
+                    .forEach(keyPhrases -> System.out.printf("\t%s.%n", keyPhrases));
+            }
         }
     });
-    analyzeJobState.getEntityRecognitionPiiTasks().forEach(taskResult -> {
+    System.out.println("PII entities recognition action results:");
+    analyzeBatchActionsResult.getRecognizePiiEntitiesActionResults().forEach(actionResult -> {
         AtomicInteger counter = new AtomicInteger();
-        for (RecognizePiiEntitiesResult entitiesResult : taskResult) {
-            System.out.printf("%n%s%n", documents.get(counter.getAndIncrement()));
-            PiiEntityCollection piiEntityCollection = entitiesResult.getEntities();
-            System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
-            piiEntityCollection.forEach(entity -> System.out.printf(
-                "Recognized Personally Identifiable Information entity: %s, entity category: %s, "
-                    + "entity subcategory: %s, offset: %s, confidence score: %f.%n",
-                entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getOffset(),
-                entity.getConfidenceScore()));
+        if (!actionResult.isError()) {
+            for (RecognizePiiEntitiesResult entitiesResult : actionResult.getResult()) {
+                System.out.printf("%n%s%n", documents.get(counter.getAndIncrement()));
+                PiiEntityCollection piiEntityCollection = entitiesResult.getEntities();
+                System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
+                piiEntityCollection.forEach(entity -> System.out.printf(
+                    "Recognized Personally Identifiable Information entity: %s, entity category: %s, "
+                        + "entity subcategory: %s, offset: %s, confidence score: %f.%n",
+                    entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getOffset(),
+                    entity.getConfidenceScore()));
+            }
         }
     });
 });