Analyzers - Create Or Replace

Reference

Service:: Azure AI Services

API Version:: 2024-12-01-preview

Create a new analyzer asynchronously.

PUT {endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2024-12-01-preview

URI Parameters

Name In Required Type Description

Name	In	Required	Type	Description
analyzerId	path	True	string	The unique identifier of the analyzer. Regex pattern: `^[a-zA-Z0-9._-]{1,64}$`
endpoint	path	True	string uri	Content Understanding service endpoint.
api-version	query	True	string	The API version to use for this operation.

analyzerId

path

True

string

The unique identifier of the analyzer.

Regex pattern: ^[a-zA-Z0-9._-]{1,64}$

endpoint

path

True

string

uri

Content Understanding service endpoint.

api-version

query

True

string

The API version to use for this operation.

Request Header

Name	Required	Type	Description
Operation-Id		string	A client-provided GUID to identify the long-running operation.
x-ms-client-request-id		string uuid	An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Name	Type	Description
baseAnalyzerId	string	The analyzer to incrementally train from.
config	ContentAnalyzerConfig	Analyzer configuration settings.
description	string	A description of the analyzer.
fieldSchema	FieldSchema	The schema of fields to extracted.
scenario	string	The scenario for which the analyzer is optimized.
tags	object	Tags associated with the analyzer.
trainingData	DataSource: BlobDataSource	The data source containing training data for the analyzer.

Responses

Name	Type	Description
200 OK	ContentAnalyzer	The request has succeeded. Headers Operation-Id: string Operation-Location: string x-ms-client-request-id: string
201 Created	ContentAnalyzer	The request has succeeded and a new resource has been created as a result. Headers Operation-Id: string Operation-Location: string x-ms-client-request-id: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

ContentAnalyzer

The request has succeeded.

Headers

Operation-Id: string
Operation-Location: string
x-ms-client-request-id: string

201 Created

ContentAnalyzer

The request has succeeded and a new resource has been created as a result.

Headers

Operation-Id: string
Operation-Location: string
x-ms-client-request-id: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

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

Create or Replace Custom Analyzer

Sample request

HTTP

PUT {endpoint}/contentunderstanding/analyzers/myAnalyzer?api-version=2024-12-01-preview


{
  "description": "My custom analyzer",
  "tags": {
    "createdBy": "John"
  },
  "baseAnalyzerId": "prebuilt-document",
  "config": {
    "enableFace": false,
    "enableOcr": true,
    "enableLayout": true,
    "enableBarcode": true,
    "enableFormula": false,
    "returnDetails": true
  },
  "fieldSchema": {
    "name": "MyForm",
    "description": "My custom form",
    "fields": {
      "Company": {
        "type": "string",
        "description": "Name of company."
      }
    },
    "definitions": {}
  },
  "trainingData": {
    "kind": "blob",
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingData",
    "fileListPath": "trainingData/fileList.jsonl"
  }
}

Sample response

Status code:: 200

Operation-Id: 3b31320d-8bab-4f88-b19c-2322a7f11034
Operation-Location: https://myendpoint.cognitiveservices.azure.com/contentunderstanding/analyzers/myAnalyzer/operations/3b31320d-8bab-4f88-b19c-2322a7f11034?api-version=2024-12-01-preview

{
  "analyzerId": "myAnalyzer",
  "description": "My custom analyzer",
  "tags": {
    "createdBy": "John"
  },
  "status": "creating",
  "createdAt": "2024-10-14T18:46:36.051Z",
  "lastModifiedAt": "2024-10-14T18:46:36.051Z",
  "baseAnalyzerId": "prebuilt-document",
  "config": {
    "locales": null,
    "enableFace": false,
    "enableOcr": true,
    "enableLayout": true,
    "enableBarcode": true,
    "enableFormula": false,
    "returnDetails": true
  },
  "fieldSchema": {
    "name": "MyForm",
    "description": "My custom form",
    "fields": {
      "Company": {
        "type": "string",
        "description": "Name of company."
      }
    },
    "definitions": {}
  },
  "trainingData": {
    "kind": "blob",
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer",
    "prefix": "trainingData",
    "fileListPath": "trainingData/fileList.jsonl"
  }
}

Status code:: 201

Operation-Id: 3b31320d-8bab-4f88-b19c-2322a7f11034
Operation-Location: https://myendpoint.cognitiveservices.azure.com/contentunderstanding/analyzers/myAnalyzer/operations/3b31320d-8bab-4f88-b19c-2322a7f11034?api-version=2024-12-01-preview

{
  "analyzerId": "myAnalyzer",
  "description": "My custom analyzer",
  "tags": {
    "createdBy": "John"
  },
  "status": "creating",
  "createdAt": "2024-10-14T18:46:36.051Z",
  "lastModifiedAt": "2024-10-14T18:46:36.051Z",
  "baseAnalyzerId": "prebuilt-document",
  "config": {
    "locales": null,
    "enableFace": false,
    "enableOcr": true,
    "enableLayout": true,
    "enableBarcode": true,
    "enableFormula": false,
    "returnDetails": true
  },
  "fieldSchema": {
    "name": "MyForm",
    "description": "My custom form",
    "fields": {
      "Company": {
        "type": "string",
        "description": "Name of company."
      }
    },
    "definitions": {}
  },
  "trainingData": {
    "kind": "blob",
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer",
    "prefix": "trainingData",
    "fileListPath": "trainingData/fileList.jsonl"
  }
}

Definitions

Name	Description
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	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.
BlobDataSource	Blob storage data source.
ContentAnalyzer	Analyzer that extracts content and fields from multimodal documents.
ContentAnalyzerConfig	Configuration settings for an analyzer.
DataSourceKind	Data source kind.
FieldDefinition	Definition of the field using a JSON Schema like syntax.
FieldSchema	Schema of fields to be extracted from documents.
FieldType	Semantic data type of the field value.
GenerationMethod	Generation method.
ResourceStatus	Status of a resource.

Azure.Core.Foundations.Error

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	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.

Azure.Core.Foundations.ErrorResponse

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

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	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

BlobDataSource

Blob storage data source.

Name	Type	Description
containerUrl	string	The URL of the blob container.
fileListPath	string	An optional path to a file listing specific blobs to include.
kind	string: blob	The kind of data source.
prefix	string	An optional prefix to filter blobs within the container.

ContentAnalyzer

Analyzer that extracts content and fields from multimodal documents.

Name	Type	Description
analyzerId	string	The unique identifier of the analyzer.
baseAnalyzerId	string	The analyzer to incrementally train from.
config	ContentAnalyzerConfig	Analyzer configuration settings.
createdAt	string	The date and time when the analyzer was created.
description	string	A description of the analyzer.
fieldSchema	FieldSchema	The schema of fields to extracted.
lastModifiedAt	string	The date and time when the analyzer was last modified.
scenario	string	The scenario for which the analyzer is optimized.
status	ResourceStatus	The status of the analyzer.
tags	object	Tags associated with the analyzer.
trainingData	DataSource: BlobDataSource	The data source containing training data for the analyzer.
warnings	Azure.Core.Foundations.Error[]	Warnings encountered while creating the analyzer.

ContentAnalyzerConfig

Configuration settings for an analyzer.

Name	Type	Description
enableBarcode	boolean	Enable barcode detection.
enableFace	boolean	Enable face detection.
enableFormula	boolean	Enable mathematical formula detection.
enableLayout	boolean	Enable layout analysis.
enableOcr	boolean	Enable optical character recognition (OCR).
locales	string[]	List of locale hints for speech transcription.
returnDetails	boolean	Return all content details.

DataSourceKind

Data source kind.

Name	Type	Description
blob	string	A blob storage data source.

FieldDefinition

Definition of the field using a JSON Schema like syntax.

Name	Type	Default value	Description
$ref	string		Reference to another field definition.
description	string		Field description.
enum	string[]		Enumeration of possible field values.
enumDescriptions	object		Descriptions for each enumeration value.
examples	string[]		Examples of field values.
items	FieldDefinition		Field type schema of each array element, if type is array.
method	GenerationMethod	generate	Generation method.
properties	<string, FieldDefinition>		Named sub-fields, if type is object.
type	FieldType		Semantic data type of the field value.

FieldSchema

Schema of fields to be extracted from documents.

Name	Type	Description
definitions	<string, FieldDefinition>	Additional definitions referenced by the fields in the schema.
description	string	A description of the field schema.
fields	<string, FieldDefinition>	The fields defined in the schema.
name	string	The name of the field schema.

FieldType

Semantic data type of the field value.

Name	Type	Description
array	string	List of subfields of the same type.
boolean	string	Boolean value.
date	string	Date, normalized to ISO 8601 (YYYY-MM-DD) format.
integer	string	Integer as 64-bit signed integer.
number	string	Number as double precision floating point.
object	string	Named list of subfields.
string	string	Plain text.
time	string	Time, normalized to ISO 8601 (hh:mm:ss) format.

GenerationMethod

Generation method.

Name	Type	Description
classify	string	Values are classified against a predefined set of categories.
extract	string	Values are extracted as they appear in the content.
generate	string	Values are generated freely based on the content.

ResourceStatus

Status of a resource.

Name	Type	Description
creating	string	The resource is being created.
deleting	string	The resource is being deleted.
failed	string	The resource failed during creation.
ready	string	The resource is ready.

Share via

Analyzers - Create Or Replace

URI Parameters

Request Header

Request Body

Responses

Security

Ocp-Apim-Subscription-Key

OAuth2Auth

Scopes

Examples

Create or Replace Custom Analyzer

Sample request

Sample response

Definitions

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

BlobDataSource

ContentAnalyzer

ContentAnalyzerConfig

DataSourceKind

FieldDefinition

FieldSchema

FieldType

GenerationMethod

ResourceStatus

Additional resources