feat: Added client library support for ModerateText in the Natural Language API (V1Beta2)

Google APIs · copybara-github · commit 392db1d5b03a · 2023-05-24T14:08:29.000-07:00
PiperOrigin-RevId: 534975458
diff --git a/google/cloud/language/v1beta2/BUILD.bazel b/google/cloud/language/v1beta2/BUILD.bazel
@@ -220,6 +220,7 @@ php_gapic_library(
     name = "language_php_gapic",
     srcs = [":language_proto_with_info"],
     grpc_service_config = "language_grpc_service_config.json",
+    migration_mode = "PRE_MIGRATION_SURFACE_ONLY",
     rest_numeric_enums = True,
     service_yaml = "language_v1beta2.yaml",
     transport = "grpc+rest",
diff --git a/google/cloud/language/v1beta2/language_service.proto b/google/cloud/language/v1beta2/language_service.proto
@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -34,7 +34,8 @@ service LanguageService {
       "https://www.googleapis.com/auth/cloud-platform";
 
   // Analyzes the sentiment of the provided text.
-  rpc AnalyzeSentiment(AnalyzeSentimentRequest) returns (AnalyzeSentimentResponse) {
+  rpc AnalyzeSentiment(AnalyzeSentimentRequest)
+      returns (AnalyzeSentimentResponse) {
     option (google.api.http) = {
       post: "/v1beta2/documents:analyzeSentiment"
       body: "*"
@@ -46,7 +47,8 @@ service LanguageService {
   // Finds named entities (currently proper names and common nouns) in the text
   // along with entity types, salience, mentions for each entity, and
   // other properties.
-  rpc AnalyzeEntities(AnalyzeEntitiesRequest) returns (AnalyzeEntitiesResponse) {
+  rpc AnalyzeEntities(AnalyzeEntitiesRequest)
+      returns (AnalyzeEntitiesResponse) {
     option (google.api.http) = {
       post: "/v1beta2/documents:analyzeEntities"
       body: "*"
@@ -55,9 +57,12 @@ service LanguageService {
     option (google.api.method_signature) = "document";
   }
 
-  // Finds entities, similar to [AnalyzeEntities][google.cloud.language.v1beta2.LanguageService.AnalyzeEntities] in the text and analyzes
-  // sentiment associated with each entity and its mentions.
-  rpc AnalyzeEntitySentiment(AnalyzeEntitySentimentRequest) returns (AnalyzeEntitySentimentResponse) {
+  // Finds entities, similar to
+  // [AnalyzeEntities][google.cloud.language.v1beta2.LanguageService.AnalyzeEntities]
+  // in the text and analyzes sentiment associated with each entity and its
+  // mentions.
+  rpc AnalyzeEntitySentiment(AnalyzeEntitySentimentRequest)
+      returns (AnalyzeEntitySentimentResponse) {
     option (google.api.http) = {
       post: "/v1beta2/documents:analyzeEntitySentiment"
       body: "*"
@@ -87,6 +92,15 @@ service LanguageService {
     option (google.api.method_signature) = "document";
   }
 
+  // Moderates a document for harmful and sensitive categories.
+  rpc ModerateText(ModerateTextRequest) returns (ModerateTextResponse) {
+    option (google.api.http) = {
+      post: "/v1beta2/documents:moderateText"
+      body: "*"
+    };
+    option (google.api.method_signature) = "document";
+  }
+
   // A convenience method that provides all syntax, sentiment, entity, and
   // classification features in one call.
   rpc AnnotateText(AnnotateTextRequest) returns (AnnotateTextResponse) {
@@ -170,8 +184,8 @@ message Sentence {
   TextSpan text = 1;
 
   // For calls to [AnalyzeSentiment][] or if
-  // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_document_sentiment] is set to
-  // true, this field will contain the sentiment for the sentence.
+  // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_document_sentiment]
+  // is set to true, this field will contain the sentiment for the sentence.
   Sentiment sentiment = 2;
 }
 
@@ -310,9 +324,9 @@ message Entity {
   repeated EntityMention mentions = 5;
 
   // For calls to [AnalyzeEntitySentiment][] or if
-  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_entity_sentiment] is set to
-  // true, this field will contain the aggregate sentiment expressed for this
-  // entity in the provided document.
+  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_entity_sentiment]
+  // is set to true, this field will contain the aggregate sentiment expressed
+  // for this entity in the provided document.
   Sentiment sentiment = 6;
 }
 
@@ -960,9 +974,9 @@ message EntityMention {
   Type type = 2;
 
   // For calls to [AnalyzeEntitySentiment][] or if
-  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_entity_sentiment] is set to
-  // true, this field will contain the sentiment expressed for this mention of
-  // the entity in the provided document.
+  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_entity_sentiment]
+  // is set to true, this field will contain the sentiment expressed for this
+  // mention of the entity in the provided document.
   Sentiment sentiment = 3;
 }
 
@@ -972,14 +986,15 @@ message TextSpan {
   string content = 1;
 
   // The API calculates the beginning offset of the content in the original
-  // document according to the [EncodingType][google.cloud.language.v1beta2.EncodingType] specified in the API request.
+  // document according to the
+  // [EncodingType][google.cloud.language.v1beta2.EncodingType] specified in the
+  // API request.
   int32 begin_offset = 2;
 }
 
 // Represents a category returned from the text classifier.
 message ClassificationCategory {
-  // The name of the category representing the document, from the [predefined
-  // taxonomy](https://cloud.google.com/natural-language/docs/categories).
+  // The name of the category representing the document.
   string name = 1;
 
   // The classifier's confidence of the category. Number represents how certain
@@ -990,9 +1005,7 @@ message ClassificationCategory {
 // Model options available for classification requests.
 message ClassificationModelOptions {
   // Options for the V1 model.
-  message V1Model {
-
-  }
+  message V1Model {}
 
   // Options for the V2 model.
   message V2Model {
@@ -1043,7 +1056,8 @@ message AnalyzeSentimentResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1beta2.Document.language] field for more details.
+  // See [Document.language][google.cloud.language.v1beta2.Document.language]
+  // field for more details.
   string language = 2;
 
   // The sentiment for all the sentences in the document.
@@ -1066,7 +1080,8 @@ message AnalyzeEntitySentimentResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1beta2.Document.language] field for more details.
+  // See [Document.language][google.cloud.language.v1beta2.Document.language]
+  // field for more details.
   string language = 2;
 }
 
@@ -1086,7 +1101,8 @@ message AnalyzeEntitiesResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1beta2.Document.language] field for more details.
+  // See [Document.language][google.cloud.language.v1beta2.Document.language]
+  // field for more details.
   string language = 2;
 }
 
@@ -1109,7 +1125,8 @@ message AnalyzeSyntaxResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1beta2.Document.language] field for more details.
+  // See [Document.language][google.cloud.language.v1beta2.Document.language]
+  // field for more details.
   string language = 3;
 }
 
@@ -1129,12 +1146,24 @@ message ClassifyTextResponse {
   repeated ClassificationCategory categories = 1;
 }
 
+// The document moderation request message.
+message ModerateTextRequest {
+  // Required. Input document.
+  Document document = 1 [(google.api.field_behavior) = REQUIRED];
+}
+
+// The document moderation response message.
+message ModerateTextResponse {
+  // Harmful and sensitive categories representing the input document.
+  repeated ClassificationCategory moderation_categories = 1;
+}
+
 // The request message for the text annotation API, which can perform multiple
 // analysis types (sentiment, entities, and syntax) in one call.
 message AnnotateTextRequest {
   // All available features for sentiment, syntax, and semantic analysis.
   // Setting each one to true will enable that specific analysis for the input.
-  // Next ID: 11
+  // Next ID: 12
   message Features {
     // Extract syntax information.
     bool extract_syntax = 1;
@@ -1154,6 +1183,9 @@ message AnnotateTextRequest {
     // taxonomy](https://cloud.google.com/natural-language/docs/categories).
     bool classify_text = 6;
 
+    // Moderate the document for harmful and sensitive categories.
+    bool moderate_text = 11;
+
     // The model options to use for classification. Defaults to v1 options
     // if not specified. Only used if `classify_text` is set to true.
     ClassificationModelOptions classification_model_options = 10;
@@ -1191,9 +1223,13 @@ message AnnotateTextResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1beta2.Document.language] field for more details.
+  // See [Document.language][google.cloud.language.v1beta2.Document.language]
+  // field for more details.
   string language = 5;
 
   // Categories identified in the input document.
   repeated ClassificationCategory categories = 6;
+
+  // Harmful and sensitive categories identified in the input document.
+  repeated ClassificationCategory moderation_categories = 8;
 }
