DocumentModelAdministrationClient class

リソース エンドポイントと静的 API キー (KeyCredential) から DocumentModelAdministrationClient インスタンスを作成する

例:

import { DocumentModelAdministrationClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new AzureKeyCredential("<api key>");

const client = new DocumentModelAdministrationClient(endpoint, credential);

new DocumentModelAdministrationClient(endpoint: string, credential: KeyCredential, options?: DocumentModelAdministrationClientOptions)

パラメーター

リソース エンドポイントと Azure ID TokenCredentialから DocumentModelAdministrationClient インスタンスを作成します。

Azure Active Directory での認証の @azure/identity 詳細については、パッケージを参照してください。

例:

import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new DefaultAzureCredential();

const client = new DocumentModelAdministrationClient(endpoint, credential);

new DocumentModelAdministrationClient(endpoint: string, credential: TokenCredential, options?: DocumentModelAdministrationClientOptions)

パラメーター

指定された分類子 ID とドキュメントの種類を使用して、新しいドキュメント分類子を作成します。

分類子 ID は、リソース内の分類子間で一意である必要があります。

ドキュメントの種類は、ドキュメントの種類の名前を、そのドキュメントの種類のトレーニング データ セットにマップするオブジェクトとして指定されます。 次の 2 つのトレーニング データ入力方法がサポートされています。

• azureBlobSourceは、指定された Azure Blob Storage コンテナー内のデータを使用して分類子をトレーニングします。
• azureBlobFileListSourceに似ています azureBlobSource が、JSONL 形式のファイル リストを使用して、トレーニング データ セットに含まれるファイルをより詳細に制御できます。

Form Recognizer サービスは、サービス バックエンドがコンテナーと通信できるようにする SAS トークンを使用して、コンテナーへの URL として指定された Azure Storage コンテナーからトレーニング データ セットを読み取ります。 少なくとも、"読み取り" と "リスト" のアクセス許可が必要です。 さらに、特定のコンテナー内のデータは、特定の規則に従って整理する必要があります。これは、 カスタム ドキュメント分類子を構築するためのサービスのドキュメントに記載されています。

例

const classifierId = "aNewClassifier";
const containerUrl1 = "<training data container SAS URL 1>";
const containerUrl2 = "<training data container SAS URL 2>";

const poller = await client.beginBuildDocumentClassifier(
  classifierId,
  {
    // The document types. Each entry in this object should map a document type name to a
    // `ClassifierDocumentTypeDetails` object
    "formX": {
      azureBlobSource: {
        containerUrl: containerUrl1,
      }
    },
    "formY": {
      azureBlobFileListSource: {
        containerUrl: containerUrl2,
        fileList: "path/to/fileList.jsonl"
      }
    },
  },
  {
    // Optionally, a text description may be attached to the classifier
    description: "This is an example classifier!"
  }
);

// Classifier building, like model creation operations, returns a poller that eventually produces a
// DocumentClassifierDetails object
const classifierDetails = await poller.pollUntilDone();

const {
  classifierId, // identical to the classifierId given when creating the classifier
  description, // identical to the description given when creating the classifier (if any)
  createdOn, // the Date (timestamp) that the classifier was created
  docTypes // information about the document types in the classifier and their details
} = classifierDetails;

function beginBuildDocumentClassifier(classifierId: string, docTypeSources: DocumentClassifierDocumentTypeSources, options?: BeginBuildDocumentClassifierOptions): Promise<DocumentClassifierPoller>

パラメーター

戻り値

作成された分類子の詳細またはエラーを最終的に生成する実行時間の長い操作 (ポーリング)

モデル コンテンツ ソースから特定の ID を使用して新しいモデルを構築します。

モデル ID は、"事前構築済み" で始まらない限り (これらのモデルはすべてのリソースに共通する事前構築済みのForm Recognizer モデルを参照するため)、リソース内にまだ存在しない限り、任意のテキストで構成できます。

コンテンツ ソースでは、入力トレーニング データを読み取るためにサービスが使用するメカニズムについて説明します。 詳細については、 <xref:DocumentModelContentSource> 型を参照してください。

例

const modelId = "aNewModel";

const poller = await client.beginBuildDocumentModel(modelId, { containerUrl: "<SAS-encoded blob container URL>" }, {
  // Optionally, a text description may be attached to the model
  description: "This is an example model!"
});

// Model building, like all other model creation operations, returns a poller that eventually produces a ModelDetails
// object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the model
  description, // identical to the description given when creating the model
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types in the model and their field schemas
} = modelDetails;

function beginBuildDocumentModel(modelId: string, contentSource: DocumentModelSource, buildMode: DocumentModelBuildMode, options?: BeginBuildDocumentModelOptions): Promise<DocumentModelPoller>

パラメーター

戻り値

作成されたモデル情報またはエラーを最終的に生成する実行時間の長い操作 (ポーリング)

一連の入力ドキュメントとラベル付きフィールドから、指定された ID を使用して新しいモデルを構築します。

モデル ID は、"事前構築済み" で始まらない限り (これらのモデルはすべてのリソースに共通する事前構築済みのForm Recognizer モデルを参照するため)、リソース内にまだ存在しない限り、任意のテキストで構成できます。

Form Recognizer サービスは、サービス バックエンドがコンテナーと通信できるようにする SAS トークンを使用して、コンテナーへの URL として指定された Azure Storage コンテナーからトレーニング データ セットを読み取ります。 少なくとも、"読み取り" と "リスト" のアクセス許可が必要です。 さらに、特定のコンテナー内のデータは、 カスタム モデルを構築するためのサービスのドキュメントに記載されている特定の規則に従って整理する必要があります。

例

const modelId = "aNewModel";
const containerUrl = "<training data container SAS URL>";

const poller = await client.beginBuildDocumentModel(modelId, containerUrl, {
  // Optionally, a text description may be attached to the model
  description: "This is an example model!"
});

// Model building, like all other model creation operations, returns a poller that eventually produces a ModelDetails
// object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the model
  description, // identical to the description given when creating the model
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types in the model and their field schemas
} = modelDetails;

function beginBuildDocumentModel(modelId: string, containerUrl: string, buildMode: DocumentModelBuildMode, options?: BeginBuildDocumentModelOptions): Promise<DocumentModelPoller>

パラメーター

戻り値

作成されたモデル情報またはエラーを最終的に生成する実行時間の長い操作 (ポーリング)

既存の複数のサブモデルから 1 つの構成済みモデルを作成します。

生成される構成済みモデルは、そのコンポーネント モデルのドキュメントの種類を組み合わせ、抽出パイプラインに分類ステップを挿入して、指定された入力に最も適したコンポーネント サブモデルを決定します。

例

const modelId = "aNewComposedModel";
const subModelIds = [
  "documentType1Model",
  "documentType2Model",
  "documentType3Model"
];

// The resulting composed model can classify and extract data from documents
// conforming to any of the above document types
const poller = await client.beginComposeDocumentModel(modelId, subModelIds, {
  description: "This is a composed model that can handle several document types."
});

// Model composition, like all other model creation operations, returns a poller that eventually produces a
// ModelDetails object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the model
  description, // identical to the description given when creating the model
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types of the composed submodels
} = modelDetails;

function beginComposeDocumentModel(modelId: string, componentModelIds: Iterable<string>, options?: BeginComposeDocumentModelOptions): Promise<DocumentModelPoller>

パラメーター

戻り値

作成されたモデル情報またはエラーを最終的に生成する実行時間の長い操作 (ポーリング)

指定された ID を持つモデルを、特定のコピー承認によってエンコードされたリソースとモデル ID にコピーします。

「CopyAuthorization」と「getCopyAuthorization」を参照してください。

例

// We need a client for the source model's resource
const sourceEndpoint = "https://<source resource name>.cognitiveservices.azure.com";
const sourceCredential = new AzureKeyCredential("<source api key>");
const sourceClient = new DocumentModelAdministrationClient(sourceEndpoint, sourceCredential);

// We create the copy authorization using a client authenticated with the destination resource. Note that these two
// resources can be the same (you can copy a model to a new ID in the same resource).
const copyAuthorization = await client.getCopyAuthorization("<destination model ID>");

// Finally, use the _source_ client to copy the model and await the copy operation
const poller = await sourceClient.beginCopyModelTo("<source model ID>");

// Model copying, like all other model creation operations, returns a poller that eventually produces a ModelDetails
// object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the copy authorization
  description, // identical to the description given when creating the copy authorization
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types of the model (identical to the original, source model)
} = modelDetails;

function beginCopyModelTo(sourceModelId: string, authorization: CopyAuthorization, options?: BeginCopyModelOptions): Promise<DocumentModelPoller>

パラメーター

戻り値

コピーされたモデル情報またはエラーを最終的に生成する実行時間の長い操作 (ポーリング)

指定された ID を持つ分類子が存在する場合は、クライアントのリソースから削除します。 この操作を元に戻すことはできません。

例

await client.deleteDocumentClassifier("<classifier ID to delete>"));

function deleteDocumentClassifier(classifierId: string, options?: OperationOptions): Promise<void>

パラメーター

戻り値

指定された ID を持つモデルが存在する場合は、クライアントのリソースから削除します。 この操作を元に戻すことはできません。

例

await client.deleteDocumentModel("<model ID to delete>"));

function deleteDocumentModel(modelId: string, options?: DeleteDocumentModelOptions): Promise<void>

パラメーター

戻り値

メソッドで使用される、モデルをリソースにコピーする承認を beginCopyModelTo 作成します。

は CopyAuthorization 、承認にエンコードされたモデル ID とオプションの説明を使用して、このクライアントのリソースにモデルを作成する権限を別のコグニティブ サービス リソースに付与します。

例

// The copyAuthorization data structure stored below grants any cognitive services resource the right to copy a
// model into the client's resource with the given destination model ID.
const copyAuthorization = await client.getCopyAuthorization("<destination model ID>");

function getCopyAuthorization(destinationModelId: string, options?: GetCopyAuthorizationOptions): Promise<CopyAuthorization>

パラメーター

戻り値

指定された modelId と省略可能な説明をエンコードするコピー承認

分類子 (DocumentClassifierDetails) に関する情報を ID で取得します。

例

const classifierId = "<classifier ID";

const {
  classifierId, // identical to the ID given when calling `getDocumentClassifier`
  description, // a textual description of the classifier, if provided during classifier creation
  createdOn, // the Date (timestamp) that the classifier was created
  // information about the document types in the classifier and their corresponding traning data
  docTypes
} = await client.getDocumentClassifier(classifierId);

// The `docTypes` property is a map of document type names to information about the training data
// for that document type.
for (const [docTypeName, classifierDocTypeDetails] of Object.entries(docTypes)) {
 console.log(`- '${docTypeName}': `, classifierDocTypeDetails);
}

function getDocumentClassifier(classifierId: string, options?: OperationOptions): Promise<DocumentClassifierDetails>

パラメーター

戻り値

指定された ID を持つ分類子に関する情報

モデル (DocumentModelDetails) に関する情報を ID で取得します。

このメソッドは、カスタム モデルと事前構築済みモデルに関する情報を取得できます。

破壊的変更

以前のバージョンのForm Recognizer REST API と SDK では、getModelエラーが原因で作成に失敗したモデルであっても、 メソッドは任意のモデルを返す可能性がありました。 新しいサービス バージョンでは、 getDocumentModellistDocumentModels正常に作成されたモデル (つまり、使用できる "準備完了" のモデル) のみを生成します。 失敗したモデルは、"operations" API を介して取得されるようになりました。 getOperation と listOperations に関するページを参照してください。

例

// The ID of the prebuilt business card model
const modelId = "prebuilt-businessCard";

const {
  modelId, // identical to the modelId given when calling `getDocumentModel`
  description, // a textual description of the model, if provided during model creation
  createdOn, // the Date (timestamp) that the model was created
  // information about the document types in the model and their field schemas
  docTypes: {
    // the document type of the prebuilt business card model
    "prebuilt:businesscard": {
      // an optional, textual description of this document type
      description,
      // the schema of the fields in this document type, see the FieldSchema type
      fieldSchema,
      // the service's confidences in the fields (an object with field names as properties and numeric confidence
      // values)
      fieldConfidence
    }
  }
} = await client.getDocumentModel(modelId);

function getDocumentModel(modelId: string, options?: GetModelOptions): Promise<DocumentModelDetails>

パラメーター

戻り値

指定された ID を持つモデルに関する情報

操作 (OperationDetails) に関する情報を ID で取得します。

操作は、モデルの構築、作成、コピーなど、分析以外のタスクを表します。

function getOperation(operationId: string, options?: GetOperationOptions): Promise<OperationDetails>

パラメーター

戻り値

指定された ID を持つ操作に関する情報

例

// The ID of the operation, which should be a GUID
const operationId = "<operation GUID>";

const {
  operationId, // identical to the operationId given when calling `getOperation`
  kind, // the operation kind, one of "documentModelBuild", "documentModelCompose", or "documentModelCopyTo"
  status, // the status of the operation, one of "notStarted", "running", "failed", "succeeded", or "canceled"
  percentCompleted, // a number between 0 and 100 representing the progress of the operation
  createdOn, // a Date object that reflects the time when the operation was started
  lastUpdatedOn, // a Date object that reflects the time when the operation state was last modified
} = await client.getOperation(operationId);

このクライアントのリソースに関する基本情報を取得します。

例

const {
  // Information about the custom models in the current resource
  customDocumentModelDetails: {
    // The number of custom models in the current resource
    count,
    // The maximum number of models that the current resource can support
    limit
  }
} = await client.getResourceDetails();

function getResourceDetails(options?: GetResourceDetailsOptions): Promise<ResourceDetails>

パラメーター

戻り値

このクライアントのリソースに関する基本情報

リソース内の分類子に関する詳細を一覧表示します。 この操作では、ページングがサポートされています。

例

非同期イテレーション

for await (const details of client.listDocumentClassifiers()) {
  const {
    classifierId, // The classifier's unique ID
    description, // a textual description of the classifier, if provided during creation
    docTypes, // information about the document types in the classifier and their corresponding traning data
  } = details;
}

ページ別

// The listDocumentClassifiers method is paged, and you can iterate by page using the `byPage` method.
const pages = client.listDocumentClassifiers().byPage();

for await (const page of pages) {
  // Each page is an array of classifiers and can be iterated synchronously
  for (const details of page) {
    const {
      classifierId, // The classifier's unique ID
      description, // a textual description of the classifier, if provided during creation
      docTypes, // information about the document types in the classifier and their corresponding traning data
    } = details;
  }
}

function listDocumentClassifiers(options?: ListModelsOptions): PagedAsyncIterableIterator<DocumentClassifierDetails, DocumentClassifierDetails[], PageSettings>

パラメーター

戻り値

ページングをサポートする分類子の詳細の非同期の iterable

リソース内のモデルの概要を一覧表示します。 カスタム モデルと事前構築済みモデルが含まれます。 この操作では、ページングがサポートされています。

モデルの概要 (DocumentModelSummary) には、モデルに関する基本情報のみが含まれており、モデル内のドキュメントの種類 (フィールド スキーマや信頼度値など) に関する情報は含まれません。

モデルに関する完全な情報にアクセスするには、 getDocumentModel を使用します。

破壊的変更

以前のバージョンの Form Recognizer REST API と SDK では、listModelsエラーが原因で作成に失敗したモデルであっても、メソッドはすべてのモデルを返していました。 新しいサービス バージョンでは、 listDocumentModelsgetDocumentModel正常に作成されたモデル (つまり、使用できる "準備完了" のモデル) のみを生成します。 失敗したモデルは、"operations" API を介して取得されるようになりました。 getOperation と listOperations に関するページを参照してください。

例

非同期イテレーション

for await (const summary of client.listDocumentModels()) {
  const {
    modelId, // The model's unique ID
    description, // a textual description of the model, if provided during model creation
  } = summary;

  // You can get the full model info using `getDocumentModel`
  const model = await client.getDocumentModel(modelId);
}

ページ別

// The listDocumentModels method is paged, and you can iterate by page using the `byPage` method.
const pages = client.listDocumentModels().byPage();

for await (const page of pages) {
  // Each page is an array of models and can be iterated synchronously
  for (const model of page) {
    const {
      modelId, // The model's unique ID
      description, // a textual description of the model, if provided during model creation
    } = summary;

    // You can get the full model info using `getDocumentModel`
    const model = await client.getDocumentModel(modelId);
  }
}

function listDocumentModels(options?: ListModelsOptions): PagedAsyncIterableIterator<DocumentModelSummary, DocumentModelSummary[], PageSettings>

パラメーター

戻り値

ページングをサポートするモデルの概要の非同期 iterable

リソース内のモデル作成操作を一覧表示します。 これにより、モデルを正常に作成できなかった操作を含むすべての操作が生成されます。 この操作では、ページングがサポートされています。

例

非同期イテレーション

for await (const operation of client.listOperations()) {
  const {
    operationId, // the operation's GUID
    status, // the operation status, one of "notStarted", "running", "succeeded", "failed", or "canceled"
    percentCompleted // the progress of the operation, from 0 to 100
  } = operation;
}

ページ別

// The listOperations method is paged, and you can iterate by page using the `byPage` method.
const pages = client.listOperations().byPage();

for await (const page of pages) {
  // Each page is an array of operation info objects and can be iterated synchronously
  for (const operation of page) {
    const {
      operationId, // the operation's GUID
      status, // the operation status, one of "notStarted", "running", "succeeded", "failed", or "canceled"
      percentCompleted // the progress of the operation, from 0 to 100
    } = operation;
  }
}

function listOperations(options?: ListOperationsOptions): PagedAsyncIterableIterator<OperationSummary, OperationSummary[], PageSettings>

パラメーター

戻り値

ページングをサポートする操作情報オブジェクトの非同期 iterable