Azure Document Intelligence v3.0 APIを使っている環境は、2029年3月30日までにv4.0へ移行する必要があります。対象は主に、REST APIのapi-version=2022-08-31を指定しているアプリ、古いSDKに固定しているアプリ、Document Intelligenceを組み込んだ社内ワークフローです。期限まで時間はありますが、解析結果のJSON形式、SDKのクライアント名、カスタムモデル、バッチ処理、課金条件の確認が必要になるため、まずは利用箇所の棚卸しから始めるのが安全です。Microsoft Learnでは、Document Intelligence REST API 2022-08-31 v3.0は2029年3月30日にサポート終了し、本番環境の中断を避けるためAzure Document Intelligence 2024-11-30 v4.0へ移行するよう案内されています。(Microsoft Learn)
Microsoft Azureの廃止・変更予告を整理、影響を受ける環境と期限前に確認すべきこと
今回の変更は、Azure Document Intelligenceそのものが終了するという話ではありません。廃止対象は、Azure Document Intelligence REST API v3.0、つまり2022-08-31のAPIバージョンです。
請求書、領収書、本人確認書類、PDF、帳票、契約書などを読み取り、OCRや構造化データ抽出に利用しているシステムでは、APIバージョンやSDKの固定が残っていないかを確認する必要があります。
| 確認項目 | 内容 |
|---|---|
| 廃止対象 | Azure Document Intelligence REST API 2022-08-31 v3.0 |
| 廃止日 | 2029年3月30日 |
| 推奨移行先 | Azure Document Intelligence 2024-11-30 v4.0 |
| 影響が出やすい箇所 | REST API呼び出し、SDK、カスタムモデル、レスポンスJSONの解析処理、バッチ処理 |
| 最初にやること | コード、設定ファイル、CI/CD、ログからapi-version=2022-08-31を検索する |
特に注意したいのは、「Azureポータル上のリソースが存在しているから問題ない」と判断しないことです。今回の確認ポイントは、リソースの有無ではなく、アプリケーションやワークフローがどのAPIバージョンを呼び出しているかです。
影響を受ける可能性が高い環境
Azure Document Intelligence v3.0 API廃止の影響を受けやすいのは、次のような環境です。
| 環境・実装パターン | 確認すべきポイント |
|---|---|
| REST APIを直接呼び出しているアプリ | URLにapi-version=2022-08-31が含まれていないか |
| .NET、Java、JavaScript、PythonのSDKを使用 | SDKパッケージがv3.0相当のAPIを既定で使っていないか |
| Azure FunctionsやApp Serviceの帳票処理 | 環境変数、設定ファイル、シークレットに古いAPIバージョンが残っていないか |
| API Management経由の呼び出し | バックエンドURLやポリシーでAPIバージョンを固定していないか |
| Logic Apps、Power Automate、RPA連携 | カスタムコネクタやHTTPアクションで古いエンドポイントを呼んでいないか |
| カスタムモデルを使った抽出処理 | モデルID、学習データ、レスポンスの項目名、精度検証を再確認しているか |
| バッチ処理・夜間処理 | 大量処理時の失敗率、スループット、課金、再実行設計を検証しているか |
SDKを使っている場合も安心はできません。MicrosoftのSDK対応表では、v4.0向けのSDK 1.0.0はREST API 2024-11-30 GAを対象とし、旧来のDocumentAnalysisClientやDocumentModelAdministrationClientを使うSDKバージョンにはv3.0やv3.1を対象にするものがあります。たとえば.NET/C#の4.0.0、Javaの4.0.0、JavaScriptの4.0.0、Pythonの3.2.xはv3.0、つまり2022-08-31を対象にする整理です。(Microsoft Learn)
まずはリポジトリ全体で、次の文字列を検索してください。
rg "api-version=2022-08-31|2022-08-31|Azure\.AI\.FormRecognizer|DocumentAnalysisClient|DocumentModelAdministrationClient"rgが使えない環境では、grepでも確認できます。
grep -R "api-version=2022-08-31" .
grep -R "DocumentAnalysisClient" .
grep -R "Azure.AI.FormRecognizer" .検索対象はアプリコードだけでは不十分です。Dockerfile、Terraform、Bicep、ARMテンプレート、GitHub Actions、Azure DevOps Pipeline、環境変数、API Managementポリシー、運用手順書、社内SDK、共通ライブラリまで含めて確認しましょう。
v4.0への移行で変わる主なポイント
移行先となるAzure Document Intelligence v4.0は、REST API 2024-11-30 GAとして一般提供されています。Microsoft Learnでは、v4.0のプログラミング言語SDKもGAとなり、最新のクライアントライブラリは2024-11-30 REST APIを既定で対象にすると説明されています。(Microsoft Learn)
v4.0への移行は、単にURLのapi-versionを書き換えるだけで終わらない可能性があります。特に、解析結果を独自ロジックでパースしている場合は注意が必要です。
SDKとクライアント名の変更を確認する
v4.0では、SDKのパッケージやクライアントが従来のForm Recognizer系からDocument Intelligence系へ整理されています。MicrosoftのSDKページでは、v4.0向けにDocumentIntelligenceClientとDocumentIntelligenceAdministrationClientが示されています。(Microsoft Learn)
移行時は、次のような観点で確認してください。
| 確認対象 | 見るべき内容 |
|---|---|
| パッケージ名 | 古いForm Recognizer系パッケージに固定されていないか |
| クライアントクラス | DocumentAnalysisClientから新しいクライアントへ置き換えが必要か |
| APIバージョン | 明示指定している場合、2024-11-30に変更しているか |
| レスポンス処理 | フィールド名、階層、配列、信頼度スコアの参照が壊れないか |
| 管理系処理 | モデル作成、一覧取得、削除などの管理APIも移行対象に含めているか |
移行作業では、「ビルドが通る」だけでは不十分です。帳票から抽出した値が、従来と同じ業務項目に正しくマッピングされているかまで確認する必要があります。
カスタム分類モデルの挙動に注意する
v4.0では、カスタム分類モデル関連にも変更があります。Microsoft Learnでは、v4.0のカスタム分類モデルは分析時に既定でドキュメントを分割しないため、古い動作を維持するにはsplitModeプロパティをautoに明示設定する必要があると説明されています。(Microsoft Learn)
これは、複数ページの帳票や複数文書をまとめて処理している環境では重要です。たとえば、1つのPDFに申込書、本人確認書類、補足資料が含まれているケースでは、分類・分割の挙動が変わると後続処理に影響します。
確認すべき例は次の通りです。
| 利用シーン | 起こり得る影響 |
|---|---|
| 複数書類を1つのPDFでアップロード | 文書分割の前提が変わり、後続の抽出処理がずれる |
| 分類結果ごとに別ワークフローへ送る | 分類単位が変わり、承認・保管・通知処理に影響する |
| ページ番号をキーにしてDB登録 | ページ構成の扱いが変わると登録データが不整合になる |
| カスタム分類器を継続利用 | v4.0で同じ精度・同じ分類結果になるか検証が必要 |
既存のv3.0処理で「分割される前提」を持っている場合は、移行テストの早い段階でsplitModeを確認してください。
Batch APIや検索可能PDFなどの新機能も評価する
v4.0では、Batch APIが読み取り、レイアウト、事前構築済みモデル、カスタムモデルを含むすべてのモデルをサポートするようになったほか、バッチジョブのLISTやDELETEもサポートされています。また、事前構築済みの読み取りモデルでは検索可能なPDFの出力において中国語、日本語、韓国語も含まれるようになっています。(Microsoft Learn)
これは単なる廃止対応ではなく、既存処理を見直す機会にもなります。
たとえば、これまで大量のPDFを1件ずつ処理していた場合、Batch APIを使った処理設計に変更することで、ジョブ管理や削除運用を整理できる可能性があります。一方で、バッチ化すると失敗時の再実行単位、監視、タイムアウト、コスト管理も変わるため、運用設計まで含めて検証しましょう。
管理者と開発者が確認すべき設定項目
Azure管理者と開発者は、役割ごとに見るべきポイントが異なります。移行漏れを防ぐには、アプリ担当だけに任せず、インフラ、セキュリティ、運用、業務部門を含めて確認するのが現実的です。
| 担当 | 確認すべき項目 | 判断基準 |
|---|---|---|
| アプリ開発者 | APIバージョン、SDK、レスポンス処理 | v3.0固定が残っていないか |
| Azure管理者 | リソース、診断ログ、ネットワーク、キー管理 | どのアプリがDocument Intelligenceを呼んでいるか把握できるか |
| セキュリティ担当 | APIキー、Managed Identity、Key Vault | キー直書きや古いシークレット運用がないか |
| 運用担当 | エラー監視、再実行、SLA、通知 | v4.0移行後の障害検知ができるか |
| 業務部門 | 抽出精度、帳票パターン、例外処理 | 業務上許容できる精度と結果か |
認証まわりも合わせて見直すと安全です。MicrosoftのSDKページでは、クラウド上で動くアプリに資格情報を保存しないため、Microsoft Entra ID認証とマネージドIDの利用が推奨されています。また、APIキーを使う場合はAzure Key Vaultなどに安全に保管し、コードへ直接含めないよう案内されています。(Microsoft Learn)
ただし、Microsoft Entra ID認証を使う場合は、エンドポイント条件にも注意が必要です。同じSDKページでは、リージョンエンドポイントはMicrosoft Entra認証をサポートせず、この認証方式を使うにはリソースのカスタムサブドメインが必要と説明されています。(Microsoft Learn)
移行前に作るべき検証データセット
Azure Document Intelligence v3.0 APIからv4.0へ移行する際は、検証用の帳票セットを必ず用意してください。APIの応答が少し変わるだけでも、後続のDB登録、承認ワークフロー、検索インデックス、請求処理に影響することがあります。
検証データセットには、きれいなサンプルだけでなく、実運用で失敗しやすいデータを含めることが重要です。
| 含めるべきデータ | 理由 |
|---|---|
| 標準的な帳票 | 基本的な抽出精度と互換性を確認する |
| 低解像度・傾き・汚れのある画像 | OCR結果の差分を確認する |
| 複数ページPDF | ページ単位、分割、表抽出の挙動を確認する |
| 手書きや押印を含む書類 | 実務上の例外パターンを確認する |
| 表が複雑な請求書・明細書 | 行・列・金額の抽出ズレを確認する |
| 旧モデルで誤認識していた帳票 | v4.0で改善・悪化していないか確認する |
| 大量処理用データ | レイテンシ、失敗率、コスト、再実行を確認する |
検証では、単純に「抽出できたか」ではなく、業務に使う項目ごとに合否を判定します。
たとえば請求書処理なら、次のような観点です。
| 項目 | 合格基準の例 |
|---|---|
| 請求書番号 | 完全一致。空欄や桁違いは不合格 |
| 請求日 | 日付形式へ正規化できること |
| 取引先名 | 表記揺れを許容するか事前に決める |
| 合計金額 | 税込・税抜の扱いを明確にする |
| 明細行 | 行数、品目、数量、単価、金額が業務上許容範囲か |
| 信頼度スコア | 閾値未満の場合の手動確認フローがあるか |
v4.0移行の実務手順
移行は、いきなり本番コードを書き換えるのではなく、棚卸し、検証、並行稼働、段階展開の順で進めるのが安全です。
| 手順 | 作業内容 | 成果物 |
|---|---|---|
| 棚卸し | v3.0 API利用箇所を洗い出す | 利用一覧、担当者、影響度 |
| 優先度付け | 本番影響、処理件数、業務重要度で分類 | 移行優先順位 |
| v4.0検証 | 同じ帳票をv3.0とv4.0で比較 | 差分レポート |
| コード修正 | SDK、APIバージョン、レスポンス処理を更新 | 移行済みブランチ |
| 業務確認 | 抽出結果を業務担当者が確認 | 合否基準、例外対応 |
| 段階展開 | 一部ユーザー・一部帳票から切り替え | リリース計画 |
| 監視強化 | エラー率、処理時間、抽出失敗、コストを監視 | ダッシュボード、アラート |
| v3.0停止 | 古いAPI呼び出しを削除・ブロック | 完了報告、運用手順更新 |
移行時にありがちな失敗は、開発環境だけで成功して本番特有の帳票を確認しないことです。特に、取引先ごとにフォーマットが異なる帳票、古いスキャナーで取り込んだ画像、海外拠点から送られるPDF、手書き混在の書類は差分が出やすいため、必ず本番に近いデータで確認しましょう。
展開時に注意すべきポイント
v4.0移行では、リリースの仕方も重要です。Document Intelligenceは業務データの入口になることが多く、障害が起きると後続の承認、請求、入金消込、本人確認、検索、保管まで止まる可能性があります。
段階的に切り替える
可能であれば、全件を一気にv4.0へ切り替えるのではなく、段階的に移行します。
| 切り替え方法 | 向いているケース |
|---|---|
| 開発・検証環境で先行移行 | すべての環境でまず実施すべき基本対応 |
| 特定帳票だけv4.0へ移行 | 帳票種別ごとに精度差を見たい場合 |
| 一部ユーザー・一部部署だけ移行 | 業務影響を限定したい場合 |
| 並行実行して結果比較 | 精度やレスポンス差分を定量的に見たい場合 |
| フィーチャーフラグで切り替え | 迅速なロールバックが必要な場合 |
理想は、一定期間v3.0とv4.0を並行実行し、抽出結果の差分を記録することです。処理コストは増える可能性がありますが、移行後の業務トラブルを減らせます。
課金とトレーニング回数を確認する
カスタムニューラルモデルを使っている場合は、移行検証中のトレーニング回数にも注意が必要です。Microsoft Learnでは、v4.0 APIから、カレンダー月の20回を超えるトレーニング要求はトレーニング階層で課金されると説明されています。(Microsoft Learn)
検証時に何度もモデルを作り直す場合は、次のルールを決めておくと無駄なコストを防げます。
| ルール | 目的 |
|---|---|
| トレーニング実行者を限定する | 不要な再学習を防ぐ |
| 検証用データセットを固定する | 差分比較をしやすくする |
| 実行回数を記録する | 課金や上限超過を把握する |
| モデル命名規則を決める | 不要モデルの放置を防ぐ |
| 削除・保管ルールを決める | セキュリティと運用負荷を下げる |
期限から逆算した移行スケジュール
2029年3月30日という期限だけを見ると余裕があるように見えます。しかし、帳票処理は業務部門の確認が必要になりやすく、移行には時間がかかります。特に、カスタムモデル、基幹システム連携、外部ベンダー開発、監査対応がある環境では、早めに動いた方が安全です。
| 時期 | 推奨アクション |
|---|---|
| 2026年 | 利用箇所の棚卸し、影響度分類、検証データセット作成 |
| 2027年 | 主要アプリのv4.0検証、SDK更新、業務部門レビュー |
| 2028年 | 本番移行、並行稼働、監視強化、旧API呼び出し削減 |
| 2029年1月〜3月 | 最終確認、v3.0呼び出しゼロ確認、運用手順更新 |
v2.1を使っている環境もある場合は、さらに早い対応が必要です。Microsoft Learnでは、Document Intelligence REST API v2.1は2027年9月15日にサポート終了すると案内されています。(Microsoft Learn)
移行チェックリスト
最後に、実務で使えるチェックリストとして整理します。すべてを一度に完了する必要はありませんが、まずは「どこでv3.0を使っているか」を明確にしてください。
| チェック項目 | 完了の目安 |
|---|---|
api-version=2022-08-31を検索した | コード、設定、IaC、CI/CD、運用手順書まで確認済み |
| 古いSDKを洗い出した | パッケージロックファイルと依存関係を確認済み |
| v4.0 SDKの移行方針を決めた | 言語ごとの更新方法と担当者が決まっている |
| 代表帳票でv3.0とv4.0を比較した | 抽出項目ごとの差分が記録されている |
カスタム分類のsplitModeを確認した | 複数文書・複数ページPDFの挙動を検証済み |
| レスポンスJSONの参照箇所を修正した | 後続処理、DB登録、検索連携が動作確認済み |
| 認証情報を見直した | APIキー直書きがなく、Key VaultやManaged Identityを検討済み |
| コスト影響を確認した | トレーニング回数、バッチ処理、並行実行の費用を見積もり済み |
| 段階展開の計画を作った | ロールバック方法と監視項目が決まっている |
| v3.0呼び出しを監視できる | 本番ログで古いAPIの残存を確認できる |
今回のAzure Document Intelligence v3.0 API廃止対応で最初にやるべきことは、移行作業そのものではなく、利用箇所の可視化です。2022-08-31、DocumentAnalysisClient、Azure.AI.FormRecognizerなどを手がかりに、アプリ、設定、ログ、CI/CD、外部連携を棚卸ししてください。そのうえで、v4.0の検証データセットを作り、業務上重要な帳票から順に移行すれば、2029年3月30日の期限に追われることなく安全に対応できます。
コメント