From 588bdb668cd362c2c18a4bc87cf478c64c88dabb Mon Sep 17 00:00:00 2001 From: Google APIs Date: Mon, 30 Sep 2019 14:14:55 -0700 Subject: [PATCH] Synchronize new proto/yaml changes. PiperOrigin-RevId: 272063168 --- .../language/v1beta2/language_service.proto | 228 +++++++++++------- .../language/v1beta2/language_v1beta2.yaml | 21 ++ 2 files changed, 167 insertions(+), 82 deletions(-) create mode 100644 google/cloud/language/v1beta2/language_v1beta2.yaml diff --git a/google/cloud/language/v1beta2/language_service.proto b/google/cloud/language/v1beta2/language_service.proto index 0263be04..d0242e59 100644 --- a/google/cloud/language/v1beta2/language_service.proto +++ b/google/cloud/language/v1beta2/language_service.proto @@ -1,4 +1,4 @@ -// Copyright 2017 Google Inc. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,15 +11,16 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. +// syntax = "proto3"; package google.cloud.language.v1beta2; import "google/api/annotations.proto"; -import "google/longrunning/operations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/protobuf/timestamp.proto"; -import "google/rpc/status.proto"; option go_package = "google.golang.org/genproto/googleapis/cloud/language/v1beta2;language"; option java_multiple_files = true; @@ -29,36 +30,42 @@ option java_package = "com.google.cloud.language.v1beta2"; // Provides text analysis operations such as sentiment analysis and entity // recognition. service LanguageService { + option (google.api.default_host) = "language.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-language," + "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: "*" }; + option (google.api.method_signature) = "document,encoding_type"; + option (google.api.method_signature) = "document"; } // 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: "*" }; + option (google.api.method_signature) = "document,encoding_type"; + 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: "*" }; + option (google.api.method_signature) = "document,encoding_type"; + option (google.api.method_signature) = "document"; } // Analyzes the syntax of the text and provides sentence boundaries and @@ -69,6 +76,8 @@ service LanguageService { post: "/v1beta2/documents:analyzeSyntax" body: "*" }; + option (google.api.method_signature) = "document,encoding_type"; + option (google.api.method_signature) = "document"; } // Classifies a document into categories. @@ -77,6 +86,7 @@ service LanguageService { post: "/v1beta2/documents:classifyText" body: "*" }; + option (google.api.method_signature) = "document"; } // A convenience method that provides all syntax, sentiment, entity, and @@ -86,6 +96,8 @@ service LanguageService { post: "/v1beta2/documents:annotateText" body: "*" }; + option (google.api.method_signature) = "document,features,encoding_type"; + option (google.api.method_signature) = "document,features"; } } @@ -113,6 +125,7 @@ message Document { // Google Cloud Storage URI. oneof source { // The content of the input in string format. + // Cloud audit logging exempt since it is based on user data. string content = 2; // The Google Cloud Storage URI where the file content is located. @@ -139,8 +152,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; } @@ -148,7 +161,10 @@ message Sentence { // a person, an organization, or location. The API associates information, such // as salience and mentions, with entities. message Entity { - // The type of the entity. + // The type of the entity. For most entity types, the associated metadata is a + // Wikipedia URL (`wikipedia_url`) and Knowledge Graph MID (`mid`). The table + // below lists the associated fields for entities that have different + // metadata. enum Type { // Unknown UNKNOWN = 0; @@ -165,14 +181,63 @@ message Entity { // Event EVENT = 4; - // Work of art + // Artwork WORK_OF_ART = 5; - // Consumer goods + // Consumer product CONSUMER_GOOD = 6; - // Other types + // Other types of entities OTHER = 7; + + // Phone number + // + // The metadata lists the phone number, formatted according to local + // convention, plus whichever additional elements appear in the text: + // + // * `number` - the actual number, broken down into sections as per local + // convention + // * `national_prefix` - country code, if detected + // * `area_code` - region or area code, if detected + // * `extension` - phone extension (to be dialed after connection), if + // detected + PHONE_NUMBER = 9; + + // Address + // + // The metadata identifies the street number and locality plus whichever + // additional elements appear in the text: + // + // * `street_number` - street number + // * `locality` - city or town + // * `street_name` - street/route name, if detected + // * `postal_code` - postal code, if detected + // * `country` - country, if detected< + // * `broad_region` - administrative area, such as the state, if detected + // * `narrow_region` - smaller administrative area, such as county, if + // detected + // * `sublocality` - used in Asian addresses to demark a district within a + // city, if detected + ADDRESS = 10; + + // Date + // + // The metadata identifies the components of the date: + // + // * `year` - four digit year, if detected + // * `month` - two digit month number, if detected + // * `day` - two digit day number, if detected + DATE = 11; + + // Number + // + // The metadata is the number itself. + NUMBER = 12; + + // Price + // + // The metadata identifies the `value` and `currency`. + PRICE = 13; } // The representative name for the entity. @@ -183,8 +248,9 @@ message Entity { // Metadata associated with the entity. // - // Currently, Wikipedia URLs and Knowledge Graph MIDs are provided, if - // available. The associated keys are "wikipedia_url" and "mid", respectively. + // For most entity types, the metadata is a Wikipedia URL (`wikipedia_url`) + // and Knowledge Graph MID (`mid`), if they are available. For the metadata + // associated with other entity types, see the Type table below. map metadata = 3; // The salience score associated with the entity in the [0, 1.0] range. @@ -200,12 +266,38 @@ 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; } +// Represents the text encoding that the caller uses to process the output. +// Providing an `EncodingType` is recommended because the API provides the +// beginning offsets for various outputs, such as tokens and mentions, and +// languages that natively use different text encodings may access offsets +// differently. +enum EncodingType { + // If `EncodingType` is not specified, encoding-dependent information (such as + // `begin_offset`) will be set at `-1`. + NONE = 0; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-8 encoding of the input. C++ and Go are examples of languages + // that use this encoding natively. + UTF8 = 1; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-16 encoding of the input. Java and JavaScript are examples of + // languages that use this encoding natively. + UTF16 = 2; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-32 encoding of the input. Python is an example of a language + // that uses this encoding natively. + UTF32 = 3; +} + // Represents the smallest syntactic building block of the text. message Token { // The token text. @@ -223,6 +315,7 @@ message Token { // Represents the feeling associated with the entire text or entities in // the text. +// Next ID: 6 message Sentiment { // A non-negative number in the [0, +inf) range, which represents // the absolute magnitude of sentiment regardless of score (positive or @@ -849,9 +942,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; } @@ -861,15 +954,14 @@ 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. + // The name of the category representing the document, from the [predefined + // taxonomy](/natural-language/docs/categories). string name = 1; // The classifier's confidence of the category. Number represents how certain @@ -879,8 +971,8 @@ message ClassificationCategory { // The sentiment analysis request message. message AnalyzeSentimentRequest { - // Input document. - Document document = 1; + // Required. Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; // The encoding type used by the API to calculate sentence offsets for the // sentence sentiment. @@ -894,8 +986,7 @@ 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. @@ -904,8 +995,8 @@ message AnalyzeSentimentResponse { // The entity-level sentiment analysis request message. message AnalyzeEntitySentimentRequest { - // Input document. - Document document = 1; + // Required. Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; // The encoding type used by the API to calculate offsets. EncodingType encoding_type = 2; @@ -918,15 +1009,14 @@ 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; } // The entity analysis request message. message AnalyzeEntitiesRequest { - // Input document. - Document document = 1; + // Required. Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; // The encoding type used by the API to calculate offsets. EncodingType encoding_type = 2; @@ -939,15 +1029,14 @@ 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; } // The syntax analysis request message. message AnalyzeSyntaxRequest { - // Input document. - Document document = 1; + // Required. Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; // The encoding type used by the API to calculate offsets. EncodingType encoding_type = 2; @@ -963,15 +1052,14 @@ 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; } // The document classification request message. message ClassifyTextRequest { - // Input document. - Document document = 1; + // Required. Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; } // The document classification response message. @@ -985,6 +1073,7 @@ message ClassifyTextResponse { 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: 10 message Features { // Extract syntax information. bool extract_syntax = 1; @@ -998,15 +1087,17 @@ message AnnotateTextRequest { // Extract entities and their associated sentiment. bool extract_entity_sentiment = 4; - // Classify the full document into categories. + // Classify the full document into categories. If this is true, + // the API will use the default model which classifies into a + // [predefined taxonomy](/natural-language/docs/categories). bool classify_text = 6; } - // Input document. - Document document = 1; + // Required. Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; - // The enabled features. - Features features = 2; + // Required. The enabled features. + Features features = 2 [(google.api.field_behavior) = REQUIRED]; // The encoding type used by the API to calculate offsets. EncodingType encoding_type = 3; @@ -1034,36 +1125,9 @@ 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; } - -// Represents the text encoding that the caller uses to process the output. -// Providing an `EncodingType` is recommended because the API provides the -// beginning offsets for various outputs, such as tokens and mentions, and -// languages that natively use different text encodings may access offsets -// differently. -enum EncodingType { - // If `EncodingType` is not specified, encoding-dependent information (such as - // `begin_offset`) will be set at `-1`. - NONE = 0; - - // Encoding-dependent information (such as `begin_offset`) is calculated based - // on the UTF-8 encoding of the input. C++ and Go are examples of languages - // that use this encoding natively. - UTF8 = 1; - - // Encoding-dependent information (such as `begin_offset`) is calculated based - // on the UTF-16 encoding of the input. Java and Javascript are examples of - // languages that use this encoding natively. - UTF16 = 2; - - // Encoding-dependent information (such as `begin_offset`) is calculated based - // on the UTF-32 encoding of the input. Python is an example of a language - // that uses this encoding natively. - UTF32 = 3; -} diff --git a/google/cloud/language/v1beta2/language_v1beta2.yaml b/google/cloud/language/v1beta2/language_v1beta2.yaml new file mode 100644 index 00000000..bb383eb0 --- /dev/null +++ b/google/cloud/language/v1beta2/language_v1beta2.yaml @@ -0,0 +1,21 @@ +type: google.api.Service +config_version: 3 +name: language.googleapis.com +title: Cloud Natural Language API + +apis: +- name: google.cloud.language.v1beta2.LanguageService + +documentation: + summary: |- + Provides natural language understanding technologies, such as sentiment + analysis, entity recognition, entity sentiment analysis, and other text + annotations, to developers. + +authentication: + rules: + - selector: 'google.cloud.language.v1beta2.LanguageService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-language, + https://www.googleapis.com/auth/cloud-platform