Azure DocumentIntelligence (旧称 FormRecognizer) JavaScript 用 REST クライアントライブラリ - バージョン 1.1.0

2025-05-14

ドキュメントからコンテンツ、レイアウト、構造化データを抽出します。

このライブラリを使用するには、REST クライアントドキュメントに大きく依存してください

注: Form Recognizer はドキュメントインテリジェンスにブランド変更されました。からへの移行ガイドを確認してください。

主要なリンク:

ソースコードの
パッケージ (NPM)
API リファレンスドキュメントの
サンプル
変更履歴
Form Recognizer からの移行ガイド

このバージョンのクライアントライブラリの既定値は、サービスの "2024-11-30" バージョンです。

次の表は、SDK バージョンとサポートされている API バージョンのサービス間の関係を示しています。

SDK のバージョン	サポートされている API バージョンのサービス
1.0.0	2024-11-30

@azure/ai-form-recognizer や "prebuilt-businessCard"など、廃止されたモデルについては、古いサービス API バージョンを通じて古い "prebuilt-document" ライブラリに依存してください。詳細については、「Changelog」を参照してください。

次の表は、各クライアントの関係と、サポートされている API バージョンを示しています。

サービス API のバージョン	サポートされているクライアント	パッケージ
2024-11-30	DocumentIntelligenceクライアント	`@azure-rest/ai-document-intelligence` バージョンの `^1.0.0`
2023-07-31	DocumentAnalysisClient と DocumentModelAdministrationClient	`@azure/ai-form-recognizer` バージョンの `^5.0.0`
2022-08-01	DocumentAnalysisClient と DocumentModelAdministrationClient	`@azure/ai-form-recognizer` バージョンの `^4.0.0`

はじめ

現在サポートされている環境

Node.js の LTS バージョン

前提条件

このパッケージを使用するには、Azure サブスクリプションが必要です。

`@azure-rest/ai-document-intelligence` パッケージをインストールする

次の npmを使用して、JavaScript 用の Azure DocumentIntelligence(旧称FormRecognizer) REST クライアント REST クライアントライブラリをインストールします。

npm install @azure-rest/ai-document-intelligence

`DocumentIntelligenceClient` を作成して認証する

Azure Active Directory (AAD) トークン資格情報を使用するには、@azure/ID ライブラリから取得した目的の資格情報の種類のインスタンスを指定します。

AAD で認証するには、最初に npm をインストール @azure/identity 必要があります

セットアップ後、使用するから @azure/identity の種類を選択できます。たとえば、DefaultAzureCredential 使用してクライアントを認証できます。

AAD アプリケーションのクライアント ID、テナント ID、クライアントシークレットの値を環境変数として設定します(AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET

トークン資格情報の使用

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

API キーの使用

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
  key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
});

ソブリンクラウド

credentials オプションで scopes フィールドを指定して、別の Azure クラウド環境 (Azure China や Azure Government など) に接続し、KnownDocumentIntelligenceAudience の適切な値を使用します。

import DocumentIntelligence, { KnownDocumentIntelligenceAudience } from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
  {
    credentials: {
      // Use the correct audience for your cloud environment
      scopes: [KnownDocumentIntelligenceAudience.AzureGovernment]
    }
  }
);

scopesを指定しない場合、クライアントはデフォルトで Azure パブリッククラウド (https://cognitiveservices.azure.com) になります。

ドキュメントモデル

事前構築済みレイアウトの分析 (urlSource)

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { locale: "en-IN" },
  });

事前構築済みレイアウトの分析 (base64Source)

import DocumentIntelligence, {
  isUnexpected,
  getLongRunningPoller,
  AnalyzeOperationOutput,
} from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";
import { join } from "node:path";
import { readFile } from "node:fs/promises";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const filePath = join("./assets", "forms", "Invoice_1.pdf");
const base64Source = await readFile(filePath, { encoding: "base64" });
const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { locale: "en-IN" },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse);
const result = (await poller.pollUntilDone()).body as AnalyzeOperationOutput;
console.log(result);

バッチ分析

import DocumentIntelligence, {
  isUnexpected,
  parseResultIdFromResponse,
} from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

// 1. Analyze a batch of documents
const initialResponse = await client
  .path("/documentModels/{modelId}:analyzeBatch", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      azureBlobSource: {
        containerUrl: process.env["DOCUMENT_INTELLIGENCE_BATCH_TRAINING_DATA_CONTAINER_SAS_URL"],
      },
      resultContainerUrl:
        process.env["DOCUMENT_INTELLIGENCE_BATCH_TRAINING_DATA_RESULT_CONTAINER_SAS_URL"],
      resultPrefix: "result",
    },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const resultId = parseResultIdFromResponse(initialResponse);
console.log("resultId: ", resultId);

// (Optional) You can poll for the batch analysis result but be aware that a job may take unexpectedly long time, and polling could incur additional costs.
// const poller = getLongRunningPoller(client, initialResponse);
// await poller.pollUntilDone();

// 2. At a later time, you can retrieve the operation result using the resultId
const output = await client
  .path("/documentModels/{modelId}/analyzeResults/{resultId}", "prebuilt-layout", resultId)
  .get();
console.log(output);

Markdown コンテンツの形式

Markdown コンテンツ形式の出力と、既定のプレーン テキストをサポートします。現時点では、これは "事前構築済みレイアウト" でのみサポートされています。 Markdown コンテンツ形式は、チャットまたは自動化の使用シナリオで LLM を使用するためのよりわかりやすい形式と見なされます。

サービスは、Markdown 形式の GFM 仕様 (GitHub Flavored Markdown) に従います。また、結果のコンテンツ形式を示す値 "text" または "markdown" を持つ新しい contentFormat プロパティも導入します。

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { outputContentFormat: "markdown" }, // <-- new query parameter
  });

クエリフィールド

この機能フラグを指定すると、サービスは queryFields クエリパラメーターを使用して指定されたフィールドの値をさらに抽出し、モデルによってフォールバックとして定義されている既存のフィールドを補完します。

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

await client.path("/documentModels/{modelId}:analyze", "prebuilt-layout").post({
  contentType: "application/json",
  body: { urlSource: "..." },
  queryParameters: {
    features: ["queryFields"],
    queryFields: ["NumberOfGuests", "StoreNumber"],
  }, // <-- new query parameter
});

分割オプション

以前の @azure/ai-form-recognizer ライブラリでサポートされていた以前の API バージョンでは、ドキュメントの分割と分類操作 ("/documentClassifiers/{classifierId}:analyze") では、常に入力ファイルを複数のドキュメントに分割しようとしました。

より広範なシナリオのセットを有効にするために、サービスでは、新しい "2023-10-31-preview" サービスバージョンを含む "分割" クエリパラメーターが導入されています。次の値がサポートされています。

split: "auto"

サービスが分割する場所を決定します。
split: "none"

ファイル全体が 1 つのドキュメントとして扱われます。分割は実行されません。
split: "perPage"

各ページは個別のドキュメントとして扱われます。各空のページは、独自のドキュメントとして保持されます。

ドキュメント分類子の #Build

import DocumentIntelligence, {
  isUnexpected,
  getLongRunningPoller,
  DocumentClassifierBuildOperationDetailsOutput,
} from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const containerSasUrl = (): string =>
  process.env["DOCUMENT_INTELLIGENCE_TRAINING_CONTAINER_SAS_URL"];
const initialResponse = await client.path("/documentClassifiers:build").post({
  body: {
    classifierId: `customClassifier-12345`,
    description: "Custom classifier description",
    docTypes: {
      foo: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
      bar: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
    },
  },
});

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse);
const response = (await poller.pollUntilDone())
  .body as DocumentClassifierBuildOperationDetailsOutput;
console.log(response);

ドキュメント分析から生成された PDF 出力を取得する

import DocumentIntelligence, {
  isUnexpected,
  getLongRunningPoller,
  parseResultIdFromResponse,
  streamToUint8Array,
} from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";
import { join } from "node:path";
import { readFile, writeFile } from "node:fs/promises";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const filePath = join("./assets", "layout-pageobject.pdf");

const base64Source = await readFile(filePath, { encoding: "base64" });

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-read")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { output: ["pdf"] },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse);

await poller.pollUntilDone();

const output = await client
  .path(
    "/documentModels/{modelId}/analyzeResults/{resultId}/pdf",
    "prebuilt-read",
    parseResultIdFromResponse(initialResponse),
  )
  .get()
  .asNodeStream(); // output.body would be NodeJS.ReadableStream

if (output.status !== "200" || !output.body) {
  throw new Error("The response was unexpected, expected NodeJS.ReadableStream in the body.");
}

const pdfData = await streamToUint8Array(output.body);
await writeFile(`./output.pdf`, pdfData);

ドキュメント分析から、指定した図の生成されたトリミングされた画像を取得する

import DocumentIntelligence, {
  isUnexpected,
  getLongRunningPoller,
  AnalyzeOperationOutput,
  parseResultIdFromResponse,
  streamToUint8Array,
} from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";
import { join } from "node:path";
import { readFile, writeFile } from "node:fs/promises";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const filePath = join("./assets", "layout-pageobject.pdf");

const base64Source = await readFile(filePath, { encoding: "base64" });

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { output: ["figures"] },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse);

const result = (await poller.pollUntilDone()).body as AnalyzeOperationOutput;
const figures = result.analyzeResult?.figures;
const figureId = figures?.[0].id || "";

const output = await client
  .path(
    "/documentModels/{modelId}/analyzeResults/{resultId}/figures/{figureId}",
    "prebuilt-layout",
    parseResultIdFromResponse(initialResponse),
    figureId,
  )
  .get()
  .asNodeStream(); // output.body would be NodeJS.ReadableStream

if (output.status !== "200" || !output.body) {
  throw new Error("The response was unexpected, expected NodeJS.ReadableStream in the body.");
}

const imageData = await streamToUint8Array(output.body);
await writeFile(`./figures/${figureId}.png`, imageData);

情報を取得する

import DocumentIntelligence, { isUnexpected } from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const response = await client.path("/info").get();
if (isUnexpected(response)) {
  throw response.body.error;
}

console.log(response.body.customDocumentModels.limit);

ドキュメントモデルの一覧表示

import DocumentIntelligence, { isUnexpected, paginate } from "@azure-rest/ai-document-intelligence";
import { DefaultAzureCredential } from "@azure/identity";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential(),
);

const response = await client.path("/documentModels").get();
if (isUnexpected(response)) {
  throw response.body.error;
}

for await (const model of paginate(client, response)) {
  console.log(model.modelId);
}

トラブルシューティング

伐採

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

ログを有効にする方法の詳細な手順については、@azure/logger パッケージのドキュメントを参照してください。

次の方法で共有

Azure DocumentIntelligence (旧称 FormRecognizer) JavaScript 用 REST クライアント ライブラリ - バージョン 1.1.0

はじめ