Class ZCL_IBMC_NAT_LANG_UNDRSTND

Class ZCL_IBMC_NAT_LANG_UNDRSTND_V1

public inheriting from zcl_ibmc_service_ext create public

Documentation

Natural Language Understanding

Analyze various features of text content at scale. Provide text, raw HTML, or a public URL and IBM Watson Natural Language Understanding will give you results for the features you request. The service cleans HTML content before analysis by default, so the results can ignore most advertisements and other unwanted content.

You can create [custom models](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural -language-understanding-customizing) with Watson Knowledge Studio to detect custom entities and relations in Natural Language Understanding.

IBM is sunsetting Watson Natural Language Understanding Custom Sentiment (BETA). From **June 1, 2023** onward, you will no longer be able to use the Custom Sentiment feature.<br /><br />To ensure we continue providing our clients with robust and powerful text classification capabilities, IBM recently announced the general availability of a new [single-label text classification capability](https://cloud.ibm.com/docs/natural-language-understanding?topic=nat ural-language-understanding-classifications). This new feature includes extended language support and training data customizations suited for building a custom sentiment classifier.<br /><br />If you would like more information or further guidance, please contact IBM Cloud Support.{: deprecated}

Types

Visibility and Level	Name	Documentation
public	t_advanced_rules_model (structured type)	The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding. Advanced rules model.
public	t_advanced_rules_model_list (structured type)	The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding. List of advanced rules models.
public	t_advncd_rls_analysis_results type jsonobject	No documentation available.
public	t_analysis_results (structured type)	Results of the analysis, organized by feature.
public	t_analysis_results_usage (structured type)	API usage information for the request.
public	t_author (structured type)	The author of the analyzed content.
public	t_base_advanced_rules_model (structured type)	The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding. Advanced rules model.
public	t_categories_model (structured type)	Categories model.
public	t_categories_model_list (structured type)	List of categories models.
public	t_categories_options (structured type)	Returns a hierarchical taxonomy of the content. The top three categories are returned by default. Supported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.
public	t_categories_relevant_text (structured type)	Relevant text that contributed to the categorization.
public	t_categories_result (structured type)	A categorization of the analyzed text.
public	t_classifications_model (structured type)	Classifications model.
public	t_classifications_model_list (structured type)	List of classifications models.
public	t_classifications_options (structured type)	Returns text classifications for the content.
public	t_classifications_result (structured type)	A classification of the analyzed text.
public	t_clssfctns_mdl_fl_and_mtdt (structured type)	Metadata associated with this custom model.
public	t_clssfctns_mdl_fl_mtdt_and_t1 (structured type)	Metadata associated with this custom model.
public	t_clssfctns_trnng_parameters (structured type)	Optional classifications training parameters along with model train requests.
public	t_concepts_options (structured type)	Returns high-level concepts in the content. For example, a research paper about deep learning might return the concept, "Artificial Intelligence" although the term is not mentioned. Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.
public	t_concepts_result (structured type)	The general concepts referenced or alluded to in the analyzed text.
public	t_ctgrs_mdl_file_and_metadata (structured type)	Metadata associated with this custom model.
public	t_ctgrs_result_explanation (structured type)	Information that helps to explain what contributed to the categories result.
public	t_dbpedia_resource type string	Link to the corresponding DBpedia resource.
public	t_delete_model_results (structured type)	Delete model results.
public	t_disambiguation_result (structured type)	Disambiguation information for the entity.
public	t_document_emotion_results (structured type)	Emotion results for the document as a whole.
public	t_document_sentiment_results (structured type)	No documentation available.
public	t_emotion_options (structured type)	Detects anger, disgust, fear, joy, or sadness that is conveyed in the content or by the context around target phrases specified in the targets parameter. You can analyze emotion for detected entities with `entities.emotion` and for keywords with `keywords.emotion`. Supported languages: English.
public	t_emotion_result (structured type)	The detected anger, disgust, fear, joy, or sadness that is conveyed by the content. Emotion information can be returned for detected entities, keywords, or user-specified target phrases found in the text.
public	t_emotion_scores (structured type)	No documentation available.
public	t_entities_options (structured type)	Identifies people, cities, organizations, and other entities in the content. For more information, see [Entity types and subtypes](https://cloud.ibm.com/docs/natural-language-understanding?topic=natur al-language-understanding-entity-types). Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish. Arabic, Chinese, and Dutch are supported only through custom models.
public	t_entities_result (structured type)	The important people, places, geopolitical entities and other types of entities in your content.
public	t_entity_mention (structured type)	No documentation available.
public	t_error_response (structured type)	No documentation available.
public	t_features (structured type)	Analysis features and options.
public	t_features_results (structured type)	Analysis results for each requested feature.
public	t_features_results_metadata (structured type)	Webpage metadata, such as the author and the title of the page.
public	t_feature_sentiment_results (structured type)	No documentation available.
public	t_feed (structured type)	RSS or ATOM feed found on the webpage.
public	t_file_and_metadata (structured type)	Metadata associated with this custom model.
public	t_keywords_options (structured type)	Returns important keywords in the content. Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish.
public	t_keywords_result (structured type)	The important keywords in the content, organized by relevance.
public	t_list_models_results (structured type)	Custom models that are available for entities and relations.
public	t_metadata_options type jsonobject	Returns information from the document, including author name, title, RSS/ATOM feeds, prominent page image, and publication date. Supports URL and HTML input types only.
public	t_metadata_result (structured type)	The authors, publication date, title, prominent page image, and RSS/ATOM feeds of the webpage. Supports URL and HTML input types.
public	t_model (structured type)	No documentation available.
public	t_model_file_and_metadata (structured type)	Metadata associated with this custom model.
public	t_model_metadata (structured type)	Metadata associated with this custom model.
public	t_notice (structured type)	A list of messages describing model training issues when model status is `error`.
public	t_parameters (structured type)	An object containing request parameters.
public	t_relations_options (structured type)	Recognizes when two entities are related and identifies the type of relation. For example, an `awardedTo` relation might connect the entities "Nobel Prize" and "Albert Einstein". For more information, see [Relation types](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural- language-understanding-relations). Supported languages: Arabic, English, German, Japanese, Korean, Spanish. Chinese, Dutch, French, Italian, and Portuguese custom models are also supported.
public	t_relations_result (structured type)	The relations between entities found in the content.
public	t_relation_argument (structured type)	No documentation available.
public	t_relation_entity (structured type)	An entity that corresponds with an argument in a relation.
public	t_semantic_roles_action (structured type)	No documentation available.
public	t_semantic_roles_entity (structured type)	No documentation available.
public	t_semantic_roles_keyword (structured type)	No documentation available.
public	t_semantic_roles_object (structured type)	No documentation available.
public	t_semantic_roles_options (structured type)	Parses sentences into subject, action, and object form. Supported languages: English, German, Japanese, Korean, Spanish.
public	t_semantic_roles_result (structured type)	The object containing the actions and the objects the actions act upon.
public	t_semantic_roles_result_action (structured type)	The extracted action from the sentence.
public	t_semantic_roles_result_object (structured type)	The extracted object from the sentence.
public	t_semantic_roles_subject (structured type)	No documentation available.
public	t_semantic_roles_verb (structured type)	No documentation available.
public	t_sentence_result (structured type)	No documentation available.
public	t_sentiment_model (structured type)	No documentation available.
public	t_sentiment_options (structured type)	Analyzes the general sentiment of your content or the sentiment toward specific target phrases. You can analyze sentiment for detected entities with `entities.sentiment` and for keywords with `keywords.sentiment`. Supported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish.
public	t_sentiment_result (structured type)	The sentiment of the content.
public	t_smntc_roles_result_subject (structured type)	The extracted subject from the sentence.
public	t_sntmnt_mdl_file_and_metadata (structured type)	Metadata associated with this custom model.
public	t_summarization_options (structured type)	(Experimental) Returns a summary of content. Supported languages: English only. Supported regions: Dallas region only.
public	t_summarization_result (structured type)	(Experimental) Summary of content.
public	t_syntax_options (structured type)	Returns tokens and sentences from the input text.
public	t_syntax_options_tokens (structured type)	Tokenization options.
public	t_syntax_result (structured type)	Tokens and sentences returned from syntax analysis.
public	t_targeted_emotion_results (structured type)	Emotion results for a specified target.
public	t_targeted_sentiment_results (structured type)	No documentation available.
public	t_token_result (structured type)	No documentation available.
public	t_usage (structured type)	Usage information.

Constants

Visibility and Level	Name	Documentation
public static	c_abapname_dictionary (structured type)	Map ABAP identifiers to service identifiers.
public static	c_required_fields (structured type)	List of required fields per type.

Methods

Visibility and Level

Name

Documentation

public instance

analyze
importing	i_parameters	type t_parameters
	i_contenttype	type string default 'application/json'
	i_accept	type string default 'application/json'
exporting	e_response	type t_analysis_results
raising	zcx_ibmc_service_exception

Analyze text

Analyzes text, HTML, or a public webpage for the following features:
- Categories
- Classifications
- Concepts
- Emotion
- Entities
- Keywords
- Metadata
- Relations
- Semantic roles
- Sentiment
- Syntax
- Summarization (Experimental)

If a language for the input text is not specified with the `language` parameter, the service [automatically detects the language](https://cloud.ibm.com/docs/natural-language-understanding?topic=natur al-language-understanding-detectable-languages).

Parameters

i_parameters	An object containing request parameters. The `features` object and one of the `text`, `html`, or `url` attributes are required.
e_response	Service return value of type T_ANALYSIS_RESULTS

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

create_categories_model
importing	i_language	type string
	i_training_data	type file
	i_training_data_content_type	type string optional
	i_name	type string optional
	i_user_metadata	type jsonobject optional
	i_description	type string optional
	i_model_version	type string optional
	i_workspace_id	type string optional
	i_version_description	type string optional
	i_contenttype	type string default 'multipart/form-data'
	i_accept	type string default 'application/json'
exporting	e_response	type t_categories_model
raising	zcx_ibmc_service_exception

Create categories model

(Beta) Creates a custom categories model by uploading training data and associated metadata. The model begins the training and deploying process and is ready to use when the `status` is `available`.

Parameters

i_language	The 2-letter language code of this model.
i_training_data	Training data in JSON format. For more information, see [Categories training data requirements](https://cloud.ibm.com/docs/natural-language-understanding?topic=n atural-language-understanding-categories##categories-training-data-requirements) .
i_training_data_content_type	The content type of trainingData.
i_name	An optional name for the model.
i_user_metadata	An optional map of metadata key-value pairs to store with this model.
i_description	An optional description of the model.
i_model_version	An optional version string.
i_workspace_id	ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
i_version_description	The description of the version.
e_response	Service return value of type T_CATEGORIES_MODEL

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

create_classifications_model
importing	i_language	type string
	i_training_data	type file
	i_training_data_content_type	type string optional
	i_name	type string optional
	i_user_metadata	type jsonobject optional
	i_description	type string optional
	i_model_version	type string optional
	i_workspace_id	type string optional
	i_version_description	type string optional
	i_training_parameters	type t_clssfctns_trnng_parameters optional
	i_contenttype	type string default 'multipart/form-data'
	i_accept	type string default 'application/json'
exporting	e_response	type t_classifications_model
raising	zcx_ibmc_service_exception

Create classifications model

Creates a custom classifications model by uploading training data and associated metadata. The model begins the training and deploying process and is ready to use when the `status` is `available`.

Parameters

i_language	The 2-letter language code of this model.
i_training_data	Training data in JSON format. For more information, see [Classifications training data requirements](https://cloud.ibm.com/docs/natural-language-understanding?topic=n atural-language-understanding-classifications#classification-training-data-requi rements).
i_training_data_content_type	The content type of trainingData.
i_name	An optional name for the model.
i_user_metadata	An optional map of metadata key-value pairs to store with this model.
i_description	An optional description of the model.
i_model_version	An optional version string.
i_workspace_id	ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
i_version_description	The description of the version.
i_training_parameters	Optional classifications training parameters along with model train requests.
e_response	Service return value of type T_CLASSIFICATIONS_MODEL

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

delete_categories_model
importing	i_model_id	type string
	i_accept	type string default 'application/json'
exporting	e_response	type t_delete_model_results
raising	zcx_ibmc_service_exception

Delete categories model

(Beta) Un-deploys the custom categories model with the given model ID and deletes all associated customer data, including any training data or binary artifacts.

Parameters

i_model_id	ID of the model.
e_response	Service return value of type T_DELETE_MODEL_RESULTS

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

delete_classifications_model
importing	i_model_id	type string
	i_accept	type string default 'application/json'
exporting	e_response	type t_delete_model_results
raising	zcx_ibmc_service_exception

Delete classifications model

Un-deploys the custom classifications model with the given model ID and deletes all associated customer data, including any training data or binary artifacts.

Parameters

i_model_id	ID of the model.
e_response	Service return value of type T_DELETE_MODEL_RESULTS

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

delete_model
importing	i_model_id	type string
	i_accept	type string default 'application/json'
exporting	e_response	type t_delete_model_results
raising	zcx_ibmc_service_exception

Delete model

Deletes a custom model

Parameters

i_model_id	Model ID of the model to delete.
e_response	Service return value of type T_DELETE_MODEL_RESULTS

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

get_appname redefinition

public instance

get_categories_model
importing	i_model_id	type string
	i_accept	type string default 'application/json'
exporting	e_response	type t_categories_model
raising	zcx_ibmc_service_exception

Get categories model details

(Beta) Returns the status of the categories model with the given model ID.

Parameters

i_model_id	ID of the model.
e_response	Service return value of type T_CATEGORIES_MODEL

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

get_classifications_model
importing	i_model_id	type string
	i_accept	type string default 'application/json'
exporting	e_response	type t_classifications_model
raising	zcx_ibmc_service_exception

Get classifications model details

Returns the status of the classifications model with the given model ID.

Parameters

i_model_id	ID of the model.
e_response	Service return value of type T_CLASSIFICATIONS_MODEL

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

get_request_prop redefinition

public instance

get_sdk_version_date redefinition

public instance

list_categories_models
importing	i_accept	type string default 'application/json'
exporting	e_response	type t_categories_model_list
raising	zcx_ibmc_service_exception

List categories models

(Beta) Returns all custom categories models associated with this service instance.

Parameters

e_response

Service return value of type T_CATEGORIES_MODEL_LIST

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

list_classifications_models
importing	i_accept	type string default 'application/json'
exporting	e_response	type t_classifications_model_list
raising	zcx_ibmc_service_exception

List classifications models

Returns all custom classifications models associated with this service instance.

Parameters

e_response

Service return value of type T_CLASSIFICATIONS_MODEL_LIST

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

list_models
importing	i_accept	type string default 'application/json'
exporting	e_response	type t_list_models_results
raising	zcx_ibmc_service_exception

List models

Lists Watson Knowledge Studio [custom entities and relations models](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural -language-understanding-customizing) that are deployed to your Natural Language Understanding service.

Parameters

e_response

Service return value of type T_LIST_MODELS_RESULTS

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

update_categories_model
importing	i_model_id	type string
	i_language	type string
	i_training_data	type file
	i_training_data_content_type	type string optional
	i_name	type string optional
	i_user_metadata	type jsonobject optional
	i_description	type string optional
	i_model_version	type string optional
	i_workspace_id	type string optional
	i_version_description	type string optional
	i_contenttype	type string default 'multipart/form-data'
	i_accept	type string default 'application/json'
exporting	e_response	type t_categories_model
raising	zcx_ibmc_service_exception

Update categories model

(Beta) Overwrites the training data associated with this custom categories model and retrains the model. The new model replaces the current deployment.

Parameters

i_model_id	ID of the model.
i_language	The 2-letter language code of this model.
i_training_data	Training data in JSON format. For more information, see [Categories training data requirements](https://cloud.ibm.com/docs/natural-language-understanding?topic=n atural-language-understanding-categories##categories-training-data-requirements) .
i_training_data_content_type	The content type of trainingData.
i_name	An optional name for the model.
i_user_metadata	An optional map of metadata key-value pairs to store with this model.
i_description	An optional description of the model.
i_model_version	An optional version string.
i_workspace_id	ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
i_version_description	The description of the version.
e_response	Service return value of type T_CATEGORIES_MODEL

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.

public instance

update_classifications_model
importing	i_model_id	type string
	i_language	type string
	i_training_data	type file
	i_training_data_content_type	type string optional
	i_name	type string optional
	i_user_metadata	type jsonobject optional
	i_description	type string optional
	i_model_version	type string optional
	i_workspace_id	type string optional
	i_version_description	type string optional
	i_training_parameters	type t_clssfctns_trnng_parameters optional
	i_contenttype	type string default 'multipart/form-data'
	i_accept	type string default 'application/json'
exporting	e_response	type t_classifications_model
raising	zcx_ibmc_service_exception

Update classifications model

Overwrites the training data associated with this custom classifications model and retrains the model. The new model replaces the current deployment.

Parameters

i_model_id	ID of the model.
i_language	The 2-letter language code of this model.
i_training_data	Training data in JSON format. For more information, see [Classifications training data requirements](https://cloud.ibm.com/docs/natural-language-understanding?topic=n atural-language-understanding-classifications#classification-training-data-requi rements).
i_training_data_content_type	The content type of trainingData.
i_name	An optional name for the model.
i_user_metadata	An optional map of metadata key-value pairs to store with this model.
i_description	An optional description of the model.
i_model_version	An optional version string.
i_workspace_id	ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
i_version_description	The description of the version.
i_training_parameters	Optional classifications training parameters along with model train requests.
e_response	Service return value of type T_CLASSIFICATIONS_MODEL

Class-based Exceptions

zcx_ibmc_service_exception

Exception being raised in case of an error.