Conversational Analysis Authoring - Import

Triggers a job to import a project. If a project with the same name already exists, the data of that project is replaced.

POST {Endpoint}/language/authoring/analyze-conversations/projects/{projectName}/:import?api-version=2023-04-01
POST {Endpoint}/language/authoring/analyze-conversations/projects/{projectName}/:import?api-version=2023-04-01&format={format}

URI Parameters

Name In Required Type Description
Endpoint
path True

string

projectName
path True

string

The name of the project to use.

api-version
query True

string

The API version to use for this operation.

format
query

ExportedProjectFormat

The format of the exported project file to use.

Request Body

Name Required Type Description
metadata True

ConversationalAnalysisAuthoringCreateProjectOptions

Represents the project metadata.

projectFileVersion True

string

The version of the exported file.

stringIndexType True

StringIndexType

Specifies the method used to interpret string offsets. For additional information see https://aka.ms/text-analytics-offsets.

assets ConversationalAnalysisAuthoringExportedProjectAssets:

Represents the project assets.

Responses

Name Type Description
202 Accepted

The request has been accepted for processing, but processing has not yet completed.

Headers

Operation-Location: string

Other Status Codes

ErrorResponse

An unexpected error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/token

Scopes

Name Description
https://cognitiveservices.azure.com/.default

Examples

Successful Import Project

Sample request

POST {Endpoint}/language/authoring/analyze-conversations/projects/EmailApp/:import?api-version=2023-04-01

{
  "projectFileVersion": "2022-05-01",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "EmailApp",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "en-us"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "Read"
      },
      {
        "category": "Delete"
      }
    ],
    "entities": [
      {
        "category": "Sender"
      },
      {
        "category": "Number",
        "regex": {
          "expressions": [
            {
              "regexKey": "UK Phone numbers",
              "language": "en-us",
              "regexPattern": "/^\\(?([0-9]{3})\\)?[-.\\s]?([0-9]{3})[-.\\s]?([0-9]{4})$/"
            }
          ]
        }
      }
    ],
    "utterances": [
      {
        "text": "Open Blake's email",
        "dataset": "Train",
        "intent": "Read",
        "entities": [
          {
            "category": "Sender",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "Delete last email",
        "language": "en-gb",
        "dataset": "Test",
        "intent": "Delete",
        "entities": []
      }
    ]
  }
}

Sample response

operation-location: {Endpoint}/language/authoring/analyze-conversations/projects/EmailApp/import/jobs/4d37982f-fded-4c2c-afe3-15953b5919b6_637858368000000000?api-version=2023-04-01

Definitions

Name Description
CompositionSetting
ConversationalAnalysisAuthoringConversationExportedEntity

Represents an entity with its components.

ConversationalAnalysisAuthoringConversationExportedIntent

Represents an exported intent of a conversational project.

ConversationalAnalysisAuthoringConversationExportedProjectAssets

Represents the exported assets of a conversational project.

ConversationalAnalysisAuthoringConversationExportedUtterance

Represents an exported utterance for a conversational project.

ConversationalAnalysisAuthoringCreateProjectOptions

Represents the options used to create or update a project.

ConversationalAnalysisAuthoringExportedConversationOrchestration

Defines the orchestration details for a Conversational project target.

ConversationalAnalysisAuthoringExportedConversationOrchestrationOptions

Represents the orchestration options for a Conversational project target.

ConversationalAnalysisAuthoringExportedEntityList

Represents a list component of an entity.

ConversationalAnalysisAuthoringExportedEntityListSynonym

Represents a list of synonyms inside a list component

ConversationalAnalysisAuthoringExportedEntityRegex

Represents a regex component of an entity.

ConversationalAnalysisAuthoringExportedEntityRegexExpression

Represents a regex expression inside a regex component. This expression follows the .NET regex syntax. For reference, check here: https://learn.microsoft.com/dotnet/standard/base-types/regular-expressions

ConversationalAnalysisAuthoringExportedEntitySublist

Represents a sub-list inside a list component.

ConversationalAnalysisAuthoringExportedLuisOrchestration

Defines the orchestration details for a LUIS application target.

ConversationalAnalysisAuthoringExportedLuisOrchestrationOptions

Represents the orchestration options for a LUIS application target.

ConversationalAnalysisAuthoringExportedPrebuiltEntity

Represents an exported prebuilt entity component

ConversationalAnalysisAuthoringExportedProject

Represents an exported project.

ConversationalAnalysisAuthoringExportedQuestionAnsweringOrchestration

Defines the orchestration details for a Question Answering project target.

ConversationalAnalysisAuthoringExportedQuestionAnsweringOrchestrationOptions

Represents the orchestration options for a Question Answering project target.

ConversationalAnalysisAuthoringExportedUtteranceEntityLabel

Represents an entity label for an utterance.

ConversationalAnalysisAuthoringOrchestrationExportedIntent

Represents an exported intent for an orchestration project.

ConversationalAnalysisAuthoringOrchestrationExportedProjectAssets

Represents the assets of an orchestration project.

ConversationalAnalysisAuthoringOrchestrationExportedUtterance

Represents an utterance of an orchestration project.

ConversationalAnalysisAuthoringProjectSettings

Represents the settings used to define the project behavior.

Error

The error object.

ErrorCode

Human-readable error code.

ErrorResponse

Error response.

ExportedProjectFormat

The format of the exported project file to use.

InnerErrorCode

Human-readable error code.

InnerErrorModel

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

OrchestrationTargetProjectKind
ProjectKind
StringIndexType

CompositionSetting

Name Type Description
combineComponents

string

When two or more components are found in the text and overlap, the components' spans are merged together into one span combining all of them.

requireExactOverlap

string

All components must overlap at the exact same characters in the text for the entity to return. If one of the defined components is not matched or predicted, the entity will not return.

returnLongestOverlap

string

When two or more components are found in the text and overlap, the component with the longest set of characters is returned.

separateComponents

string

Every component's match or prediction is returned as a separate instance of the entity.

ConversationalAnalysisAuthoringConversationExportedEntity

Represents an entity with its components.

Name Type Description
category

string

The category of the entity.

compositionSetting

CompositionSetting

The behavior to follow when the entity's components overlap with each other.

list

ConversationalAnalysisAuthoringExportedEntityList

The list component of the entity.

prebuilts

ConversationalAnalysisAuthoringExportedPrebuiltEntity[]

The prebuilt entities components.

regex

ConversationalAnalysisAuthoringExportedEntityRegex

The regex component of the entity.

requiredComponents

string[]

The required components. Allowed values are 'learned', 'list', 'prebuilts' and 'regex'.

ConversationalAnalysisAuthoringConversationExportedIntent

Represents an exported intent of a conversational project.

Name Type Description
category

string

The intent category.

ConversationalAnalysisAuthoringConversationExportedProjectAssets

Represents the exported assets of a conversational project.

Name Type Description
entities

ConversationalAnalysisAuthoringConversationExportedEntity[]

The entities defined in the project.

intents

ConversationalAnalysisAuthoringConversationExportedIntent[]

The intents defined in the project.

projectKind string:

Conversation

The type of project containing the assets.

utterances

ConversationalAnalysisAuthoringConversationExportedUtterance[]

The utterances defined in the project.

ConversationalAnalysisAuthoringConversationExportedUtterance

Represents an exported utterance for a conversational project.

Name Type Description
dataset

string

The dataset for this utterance. Allowed values are 'Train' and 'Test'.

entities

ConversationalAnalysisAuthoringExportedUtteranceEntityLabel[]

Represents the entity labels of the utterance.

intent

string

The intent of the utterance.

language

string

Represents the utterance's language. This is BCP-47 representation of a language. For example, use "en" for English, "en-gb" for English (UK), "es" for Spanish etc.

text

string

The utterance text.

ConversationalAnalysisAuthoringCreateProjectOptions

Represents the options used to create or update a project.

Name Type Description
description

string

The project description.

language

string

The project language. This is BCP-47 representation of a language. For example, use "en" for English, "en-gb" for English (UK), "es" for Spanish etc.

multilingual

boolean

Whether the project would be used for multiple languages or not.

projectKind

ProjectKind

Represents the project kind.

projectName

string

The new project name.

settings

ConversationalAnalysisAuthoringProjectSettings

The project settings.

ConversationalAnalysisAuthoringExportedConversationOrchestration

Defines the orchestration details for a Conversational project target.

Name Type Description
deploymentName

string

The name of the targeted deployment.

projectName

string

The name of the targeted project.

ConversationalAnalysisAuthoringExportedConversationOrchestrationOptions

Represents the orchestration options for a Conversational project target.

Name Type Description
conversationOrchestration

ConversationalAnalysisAuthoringExportedConversationOrchestration

The Conversational project target details.

targetProjectKind string:

Conversation

ConversationalAnalysisAuthoringExportedEntityList

Represents a list component of an entity.

Name Type Description
sublists

ConversationalAnalysisAuthoringExportedEntitySublist[]

The sub-lists of the list component.

ConversationalAnalysisAuthoringExportedEntityListSynonym

Represents a list of synonyms inside a list component

Name Type Description
language

string

Represents the language of the synonyms. This is BCP-47 representation of a language. For example, use "en" for English, "en-gb" for English (UK), "es" for Spanish etc.

values

string[]

The list of synonyms.

ConversationalAnalysisAuthoringExportedEntityRegex

Represents a regex component of an entity.

Name Type Description
expressions

ConversationalAnalysisAuthoringExportedEntityRegexExpression[]

The regex expressions of the regex component. These expressions follow the .NET regex syntax. For reference, check here: https://learn.microsoft.com/dotnet/standard/base-types/regular-expressions

ConversationalAnalysisAuthoringExportedEntityRegexExpression

Represents a regex expression inside a regex component. This expression follows the .NET regex syntax. For reference, check here: https://learn.microsoft.com/dotnet/standard/base-types/regular-expressions

Name Type Description
language

string

Represents the language of the regex expression. This is BCP-47 representation of a language. For example, use "en" for English, "en-gb" for English (UK), "es" for Spanish etc.

regexKey

string

The key of the regex expression.

regexPattern

string

The regex pattern.

ConversationalAnalysisAuthoringExportedEntitySublist

Represents a sub-list inside a list component.

Name Type Description
listKey

string

The key of the sub-list.

synonyms

ConversationalAnalysisAuthoringExportedEntityListSynonym[]

The phrases of that correspond to the sub-list.

ConversationalAnalysisAuthoringExportedLuisOrchestration

Defines the orchestration details for a LUIS application target.

Name Type Description
appId

string

The LUIS application ID.

appVersion

string

The targeted version Id.

slotName

string

The targeted slot name.

ConversationalAnalysisAuthoringExportedLuisOrchestrationOptions

Represents the orchestration options for a LUIS application target.

Name Type Description
luisOrchestration

ConversationalAnalysisAuthoringExportedLuisOrchestration

The LUIS application target details.

targetProjectKind string:

Luis

ConversationalAnalysisAuthoringExportedPrebuiltEntity

Represents an exported prebuilt entity component

Name Type Description
category

string

The prebuilt entity category.

ConversationalAnalysisAuthoringExportedProject

Represents an exported project.

Name Type Description
assets ConversationalAnalysisAuthoringExportedProjectAssets:

Represents the project assets.

metadata

ConversationalAnalysisAuthoringCreateProjectOptions

Represents the project metadata.

projectFileVersion

string

The version of the exported file.

stringIndexType

StringIndexType

Specifies the method used to interpret string offsets. For additional information see https://aka.ms/text-analytics-offsets.

ConversationalAnalysisAuthoringExportedQuestionAnsweringOrchestration

Defines the orchestration details for a Question Answering project target.

Name Type Description
projectName

string

The name of the target project.

ConversationalAnalysisAuthoringExportedQuestionAnsweringOrchestrationOptions

Represents the orchestration options for a Question Answering project target.

Name Type Description
questionAnsweringOrchestration

ConversationalAnalysisAuthoringExportedQuestionAnsweringOrchestration

The Question Answering project details.

targetProjectKind string:

QuestionAnswering

ConversationalAnalysisAuthoringExportedUtteranceEntityLabel

Represents an entity label for an utterance.

Name Type Description
category

string

The category of the entity label.

length

integer

Length for the entity text.

offset

integer

Start position for the entity text.

ConversationalAnalysisAuthoringOrchestrationExportedIntent

Represents an exported intent for an orchestration project.

Name Type Description
category

string

The intent category.

orchestration ConversationalAnalysisAuthoringExportedOrchestrationOptions:

Specifies the behavior of this intent in the orchestration flow.

ConversationalAnalysisAuthoringOrchestrationExportedProjectAssets

Represents the assets of an orchestration project.

Name Type Description
intents

ConversationalAnalysisAuthoringOrchestrationExportedIntent[]

Represents the intents of the project.

projectKind string:

Orchestration

The type of project containing the assets.

utterances

ConversationalAnalysisAuthoringOrchestrationExportedUtterance[]

Represents the utterances of the project.

ConversationalAnalysisAuthoringOrchestrationExportedUtterance

Represents an utterance of an orchestration project.

Name Type Description
dataset

string

The dataset for this utterance. Allowed values are 'Train' and 'Test'.

intent

string

The intent of the utterance.

language

string

Represents the utterance's language. This is BCP-47 representation of a language. For example, use "en" for English, "en-gb" for English (UK), "es" for Spanish etc.

text

string

The utterance text.

ConversationalAnalysisAuthoringProjectSettings

Represents the settings used to define the project behavior.

Name Type Description
confidenceThreshold

number

The threshold of the intent with the highest confidence, at which the prediction will automatically be changed to "None". The value of the threshold should be between 0 and 1 inclusive.

Error

The error object.

Name Type Description
code

ErrorCode

One of a server-defined set of error codes.

details

Error[]

An array of details about specific errors that led to this reported error.

innererror

InnerErrorModel

An object containing more specific information than the current object about the error.

message

string

A human-readable representation of the error.

target

string

The target of the error.

ErrorCode

Human-readable error code.

Name Type Description
AzureCognitiveSearchIndexLimitReached

string

AzureCognitiveSearchIndexNotFound

string

AzureCognitiveSearchNotFound

string

AzureCognitiveSearchThrottling

string

Conflict

string

Forbidden

string

InternalServerError

string

InvalidArgument

string

InvalidRequest

string

NotFound

string

OperationNotFound

string

ProjectNotFound

string

QuotaExceeded

string

ServiceUnavailable

string

Timeout

string

TooManyRequests

string

Unauthorized

string

Warning

string

ErrorResponse

Error response.

Name Type Description
error

Error

The error object.

ExportedProjectFormat

The format of the exported project file to use.

Name Type Description
Conversation

string

Specifies the format for a conversational project.

Luis

string

Specifies the format for an application that was exported from LUIS.

InnerErrorCode

Human-readable error code.

Name Type Description
AzureCognitiveSearchNotFound

string

AzureCognitiveSearchThrottling

string

EmptyRequest

string

ExtractionFailure

string

InvalidCountryHint

string

InvalidDocument

string

InvalidDocumentBatch

string

InvalidParameterValue

string

InvalidRequest

string

InvalidRequestBodyFormat

string

KnowledgeBaseNotFound

string

MissingInputDocuments

string

ModelVersionIncorrect

string

UnsupportedLanguageCode

string

InnerErrorModel

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
code

InnerErrorCode

One of a server-defined set of error codes.

details

object

Error details.

innererror

InnerErrorModel

An object containing more specific information than the current object about the error.

message

string

Error message.

target

string

Error target.

OrchestrationTargetProjectKind

Name Type Description
Conversation

string

Luis

string

QuestionAnswering

string

ProjectKind

Name Type Description
Conversation

string

A project to build natural language into apps, bots, and IoT devices.

Orchestration

string

A project to connect and orchestrate Conversation, Custom question answering and LUIS projects together in one single project.

StringIndexType

Name Type Description
Utf16CodeUnit

string

The offset and length values will correspond to UTF-16 code units. Use this option if your application is written in a language that support Unicode, for example Java, JavaScript.