MENU

Azure REST API AnalyzeText 20260515previewの変更点と移行確認ポイント

Azure

Azure REST API documentation update: [TA] AnalyzeText 20260515preview は、Azure AI Language の Analyze Text API に関する新しいプレビュー仕様を確認すべき更新です。結論から言うと、既存の安定版 2026-05-01 を本番利用している環境で、ただちに全面移行が必要になる更新ではありません。一方で、REST APIを直接呼び出しているアプリ、OpenAPIからクライアントを生成しているチーム、PII検出・要約・医療テキスト分析・カスタム分類を使う開発者は、api-version、レスポンススキーマ、PIIマスキング設定、長時間実行ジョブの扱いを確認しておくべきです。

今回の公式PRは Azure REST API specs リポジトリの LanguageAnalyzeText に対する更新で、2026-05-15-preview が現在のプレビューリリースとして設定され、安定版は 2026-05-01 とされています。PRは data-plane、new-api-version、TypeSpec などのラベルが付いたデータプレーンAPI更新であり、ARM管理プレーンのリソース作成・更新APIとは別物です。(GitHub)

目次

Azure REST APIの「AnalyzeText 20260515preview」で押さえるべき結論

今回の更新は、Azure AI Services の Azure AI Language / Analyze Text API を利用する開発者向けの仕様更新です。対象は、感情分析、キーフレーズ抽出、言語検出、名前付きエンティティ認識、PII検出、ヘルスケア向けテキスト分析、カスタムNER、カスタム分類、要約などを Analyze Text API 経由で実行しているシステムです。

特に確認すべきポイントは次の4つです。

確認ポイント実務上の意味
api-version=2026-05-15-preview の追加プレビュー機能を検証する場合は明示的にAPIバージョンを指定する
2026-05-01 安定版との使い分け本番は安定版、検証環境でプレビューを試すのが基本
PII検出・マスキング設定の拡張個人情報の伏せ字ルール、残す文字数、出力ログの扱いを再確認する
要約・言語検出・LROジョブ結果のスキーマ変化厳密なJSONパースや型固定のクライアントで失敗しないか確認する

公式仕様では、/:analyze-text の同期API、/analyze-text/jobs のジョブ送信、/analyze-text/jobs/{jobId} のステータス取得、/analyze-text/jobs/{jobId}:cancel のキャンセル操作が定義されています。認証はAPIキーとOAuth2が定義されているため、既存の Ocp-Apim-Subscription-Key 利用環境だけでなく、Microsoft Entra IDベースの認証を使う環境でも影響確認が必要です。(GitHub)

今回の更新で何が変わったのか

公式PRでは、LanguageAnalyzeText 配下のJSON、TypeSpec、READMEが更新されています。ファイル一覧では .json が54件、.tsp が10件、.md が1件変更対象として表示され、preview/2026-05-15-preview/analyzetext.json と、そのバージョン向けの多数のサンプルが追加・更新されています。(GitHub)

新しいプレビューAPIバージョンが追加された

READMEでは、現在のプレビューリリースが 2026-05-15-preview、現在の安定版が 2026-05-01 とされています。また、AutoRest用の release_2026-05-15-preview タグは preview/2026-05-15-preview/analyzetext.json を参照する設定になっています。(GitHub)

つまり、REST APIを直接呼び出す場合は、次のように api-version を明示して使い分けます。

POST {Endpoint}/language/:analyze-text?api-version=2026-05-15-preview

長時間実行ジョブの場合は、次のエンドポイントです。

POST {Endpoint}/language/analyze-text/jobs?api-version=2026-05-15-preview

注意したいのは、プレビュー版を指定しない限り、自動的に新機能が使えるわけではない点です。既存コードで api-version=2026-05-01 やそれ以前のバージョンを固定している場合、挙動はそのバージョンに従います。

長時間実行ジョブの扱いを再確認する必要がある

Analyze Text APIでは、要約、ヘルスケア分析、カスタムNERなど、処理内容によって長時間実行ジョブとして実行するケースがあります。仕様上は、ジョブ送信後に Operation-Location を受け取り、ステータスAPIで結果を確認します。プレビューのサンプルでも、ジョブ送信のレスポンスとして Operation-Location が返る形式が示されています。(GitHub)

ジョブ状態には、running、succeeded、failed だけでなく、partiallyCompleted、cancelled、cancelling なども定義されています。ポーリング処理を自作している場合、「成功か失敗だけを見る」実装だと、中断・部分完了・キャンセル中の状態を正しく扱えない可能性があります。(GitHub)

実装では、最低でも次の分岐を用意しておくと安全です。

状態推奨する処理
notStarted / running一定間隔で再取得する
succeeded結果を取得して後続処理へ進める
partiallyCompleted成功タスクと失敗タスクを分けて記録する
failedエラー内容を保存し、再実行可否を判断する
cancelling完了状態になるまで監視を続ける
cancelledキャンセル理由と対象ジョブIDを監査ログに残す

要約機能では instruction や query の扱いに注意する

要約関連のTypeSpecでは、抽出型要約に query、抽象型要約に instruction が 2026-05-15-preview で追加されています。抽出型要約の query は関連文の抽出に使われ、抽象型要約の instruction は要約生成時の指示として使われる説明になっています。(GitHub)

たとえば、問い合わせ対応ログを要約する用途では、単に「全文を短くする」だけでなく、次のような指示を設計できます。

{
  "kind": "AbstractiveSummarization",
  "taskName": "Support ticket summary",
  "parameters": {
    "summaryLength": "short",
    "instruction": "障害原因、影響範囲、次の対応を運用担当者向けに要約してください"
  }
}

ただし、要約結果は生成モデルの出力であり、完全に固定された文字列として扱うべきではありません。テストでは「完全一致」ではなく、必須項目が含まれているか、長さが許容範囲か、禁止語が含まれていないかといった基準で検証する方が現実的です。

PII検出ではマスキングポリシーの確認が重要

PII Entity Recognitionでは、2026-05-01 で excludePiiCategories、valueExclusionPolicy、entitySynonyms、redactionPolicies、confidenceScoreThreshold、disableEntityValidation などの設定が追加されています。さらに 2026-05-15-preview では、文字マスクポリシーに unmaskLength と unmaskFromEnd が追加され、検出されたPIIの一部だけを伏せずに残す設定が可能になる仕様です。(GitHub)

たとえば、問い合わせ対応画面でクレジットカード番号やIDの末尾だけを照合用に残したい場合、次のような設計が考えられます。

{
  "kind": "PiiEntityRecognition",
  "parameters": {
    "modelVersion": "latest",
    "redactionPolicies": [
      {
        "policyKind": "characterMask",
        "redactionCharacter": "*",
        "unmaskLength": 4,
        "unmaskFromEnd": true
      }
    ]
  },
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "ja",
        "text": "本人確認番号は1234567890です。"
      }
    ]
  }
}

ここでの失敗しやすいポイントは、「一部を残せる」ことを便利機能として安易に使うことです。末尾4桁だけでも、他のログや顧客情報と組み合わせると個人を特定できる場合があります。管理者は、業務上必要な最小文字数、保存期間、ログ出力先、閲覧権限をセットで決める必要があります。

PIIカテゴリにも変更があります。たとえば Neighborhood や VIN は 2026-05-15-preview で追加されたカテゴリとして定義されています。車両、住所、地域情報を扱う業務では、検出対象が増えることで、従来より多くの文字列がPIIとして抽出・マスクされる可能性があります。(GitHub)

detectedLanguage が返るケースを考慮する

2026-05-15-preview では、入力ドキュメントで language に auto を指定した場合などに、検出された言語を示す detectedLanguage を返すモデルが追加されています。また、長時間実行ジョブの入力には、自動言語検出を要求したレコード向けの defaultLanguage も追加されています。(GitHub)

日本語テキストを扱うシステムでは、ここが意外な落とし穴になります。たとえば、問い合わせ本文に英語のエラーメッセージや製品名が多い場合、言語判定が期待とずれることがあります。language を明示できる業務では ja を指定し、多言語混在の業務では auto と defaultLanguage の組み合わせを検証するのが安全です。

影響を受けるシステムと受けにくいシステム

今回の Azure REST API documentation update は、すべてのAzure利用者に影響する更新ではありません。影響範囲は、Analyze Text APIをどのように利用しているかで変わります。

利用状況影響度確認すべきこと
Azure AI Language の Analyze Text REST APIを直接呼び出している高api-version、リクエスト本文、レスポンスパース、認証方式
OpenAPI / TypeSpec からSDKやクライアントを生成している高生成コードの差分、enum追加、型変更、CIの契約テスト
Azure SDK経由で利用している中SDKがどのREST APIバージョンに対応しているか、プレビュー機能を直接指定できるか
PII検出・要約・ヘルスケア分析を本番利用している中〜高出力スキーマ、マスキング、ログ保存、モデルバージョン
ARMテンプレートやAzureリソース作成だけを管理している低今回はデータプレーンAPI更新であることを把握する
Azure AI Languageを使っていない低対応不要

PRでは APIView によるAPIレベルの変更検出が行われ、TypeSpec、C#、Python向けのAPIレビューが作成されています。SDKや生成クライアントを使うチームは、REST仕様だけでなく、利用している言語のSDK更新状況も確認してから取り込むべきです。(GitHub)

管理者が確認すべき設定ポイント

管理者は、機能そのものよりも「安全に使える状態か」を見る必要があります。特にPIIやヘルスケア系テキストを扱う環境では、APIバージョン変更が監査・セキュリティ・運用ログに影響します。

APIキーとOAuth2認証の管理

仕様では、Ocp-Apim-Subscription-Key によるAPIキー認証と、https://cognitiveservices.azure.com/.default スコープを使うOAuth2認証が定義されています。(GitHub)

管理上は、次のように分けて考えると判断しやすくなります。

認証方式向いている用途注意点
APIキー検証環境、小規模な内部ツール、既存実装の継続利用キー漏えい時の影響が大きいため、Key Vault管理とローテーションが必須
OAuth2 / Microsoft Entra ID本番アプリ、組織アカウント・サービスプリンシパルでの制御権限設計、マネージドID、トークン取得処理の実装が必要

新しいAPIバージョンを試すときは、検証環境用のリソースまたはキーを用意し、本番キーをcurlやローカルスクリプトに直接貼り付けないようにしてください。

PII処理結果をログに残しすぎない

PII検出APIは、入力テキストだけでなく、検出されたエンティティ、信頼度、オフセット、マスク後文字列などを返します。サンプルでも、SSNやABA番号などが検出され、redactedText とエンティティ情報が返る形式が示されています。(GitHub)

ログ設計では、次の方針が安全です。

ログ対象推奨
入力本文原則保存しない。必要な場合は短期間・限定権限にする
redactedText業務要件があれば保存可。ただし再識別リスクを評価する
entities.text原文のPIIが含まれるため、本番ログには残さない
confidenceScore品質分析に有用。本文やPII値と分離して保存する
modelVersion / api-version問題調査に必須。必ず保存する

「マスク後だから安全」と決めつけないことが重要です。unmaskLength を使う場合、残した文字数と他システムの顧客情報を突き合わせることで、本人特定につながる可能性があります。

モデルバージョンとAPIバージョンを混同しない

Analyze Text APIでは、REST APIの api-version と、タスクパラメータの modelVersion は別の概念です。api-version はリクエスト・レスポンスの形や利用できるパラメータを決め、modelVersion は分析に使うモデルの指定に関係します。

運用ログには、少なくとも次の情報を残してください。

api-version
modelVersion
operationId
jobId
taskName
kind
status
createdDateTime
lastUpdatedDateTime

障害調査では、「APIバージョンを変えたのか」「モデルの出力が変わったのか」「ジョブ処理が失敗したのか」を切り分ける必要があります。これらをログに残していないと、プレビュー検証時に原因特定が難しくなります。

開発者が確認すべき移行・実装ポイント

開発者は、コード上の api-version 置換だけで移行を完了させないことが重要です。REST APIのバージョン更新では、リクエストに追加できるプロパティだけでなく、レスポンスに新しいフィールドが増えることもあります。

厳密すぎるJSONパースを避ける

detectedLanguage、PIIの mask 関連フィールド、エンティティの tags や metadata など、バージョンによって返る情報が変わる可能性があります。TypeSpecでも、複数の結果モデルで 2026-05-15-preview による型変更や検出言語付きモデルが定義されています。(GitHub)

避けるべき実装は次のようなものです。

想定外のプロパティがあるとエラーにする
特定のenum値だけを許可して、それ以外を例外にする
レスポンス配列の順序だけでタスク結果を判定する

代わりに、次の実装を推奨します。

未知のプロパティは無視する
未知のenum値はログに残し、処理は安全側に倒す
taskName と kind を使って結果を対応付ける
errors と warnings を必ず確認する

stringIndexType を日本語環境で確認する

Analyze Text APIでは、エンティティの offset や length が返ります。この位置情報は、stringIndexType によって解釈が変わります。仕様では、.NET 向けの TextElements_v8、Pythonなどで使いやすい UnicodeCodePoint、JavaやJavaScript向けの Utf16CodeUnit が定義されています。(GitHub)

日本語、絵文字、結合文字を含むテキストでは、オフセットのずれが起きやすくなります。たとえば、検出されたPIIだけを画面上でハイライトする、該当部分だけを置換する、監査レポートに抜粋する、といった処理では必ず検証してください。

利用言語・用途推奨確認
JavaScript / TypeScriptUtf16CodeUnit で文字位置が画面表示と合うか確認
PythonUnicodeCodePoint 指定時のスライス位置を確認
.NETTextElements_v8 と StringInfo の扱いを確認
多言語テキスト日本語、絵文字、改行、サロゲートペアを含むテストデータを用意

SDK利用時はREST仕様との差を確認する

Azure SDKを使っている場合、REST API仕様が更新されても、すぐにSDKから全機能を使えるとは限りません。PRではC#とPythonのAPIレビューが作成されているため、SDK更新を待つか、一部だけREST直接呼び出しで検証するかを判断する必要があります。(GitHub)

実務では、次の3パターンに分けると判断しやすくなります。

状況対応
既存SDKで安定版機能だけ使うすぐに変更せず、SDKのリリースノートを確認
プレビュー機能を早期検証したい検証環境でREST直接呼び出しを使う
自動生成クライアントを使っているOpenAPI差分を取り込み、CIで契約テストを実行

「SDKにプロパティがないからAPIでも未対応」と判断するのは危険です。逆に、「REST仕様にあるからSDKで安全に使える」とも限りません。どのレイヤーで対応しているかを分けて確認してください。

展開前に実施したいテスト項目

2026-05-15-preview を試す場合は、いきなり本番トラフィックへ流すのではなく、入力データとタスク種別を絞って検証します。

テスト項目見るべき結果
既存リクエストをプレビュー版で実行HTTPステータス、エラーコード、レスポンス構造が許容範囲か
PIIマスキング想定したカテゴリが検出され、過剰・不足マスクがないか
unmaskLength 利用残した文字数が業務上必要最小限か
要約タスク出力長、指示への追従、禁止情報の混入がないか
language=auto日本語・英語混在データで detectedLanguage が妥当か
LROジョブOperation-Location、ポーリング、キャンセル、部分完了処理が動くか
SDK・生成クライアントenum追加や未知フィールドで落ちないか
監査ログ原文PIIが保存されていないか

特にPII検出では、正常系だけでなく「検出されないケース」もテストしてください。たとえば、日本語の住所、海外住所、略称、ハイフンなしの番号、全角数字、スペース混在のIDなどです。検出結果はモデルや言語、入力形式で変わるため、業務データに近いテストセットを用意する必要があります。

本番移行の判断基準

プレビュー版は、新機能の検証には有用ですが、本番の標準バージョンとして採用するかは慎重に判断する必要があります。今回のPRではレビュアーから、2026-05-15-preview は以前レビューされた 2025-11-15-preview にかなり近いというコメントもありますが、同時にAPIレベルの変更検出とレビューが行われています。差分が小さく見える場合でも、実装側の型定義や契約テストは省略しない方が安全です。(GitHub)

本番適用は、次の基準を満たしてからにしましょう。

判断基準合格ライン
機能上の必要性2026-05-15-preview 固有の機能が業務上必要
安定版との差分理解2026-05-01 で足りない理由を説明できる
セキュリティ確認PII、ログ、認証、キー管理の方針が決まっている
互換性テスト主要タスクでレスポンスパースとエラー処理を確認済み
ロールバックapi-version を戻す手順と設定管理がある
監視失敗率、レイテンシ、ジョブ滞留、キャンセル数を追跡できる

判断に迷う場合は、まず 2026-05-01 安定版を基準にし、必要な機能だけ 2026-05-15-preview で検証する構成が現実的です。

すぐに取るべきアクション

今回の Azure REST API documentation update: [TA] AnalyzeText 20260515preview で、管理者や開発者が最初に行うべきことは、既存システム内の api-version と利用タスクの棚卸しです。

まず、コード、API Management、Function App、Logic Apps、バッチ、CI/CD変数、OpenAPI生成設定から、次の文字列を検索してください。

api-version=
analyze-text
PiiEntityRecognition
AbstractiveSummarization
ExtractiveSummarization
EntityRecognition
Healthcare

次に、利用しているタスクごとに、PIIマスキング、要約指示、言語自動検出、LROポーリング、SDK対応状況を確認します。プレビュー機能を使う場合は、検証環境で 2026-05-15-preview を明示し、安定版 2026-05-01 と結果を比較してください。

本番では「新しいから切り替える」のではなく、「必要な機能があり、セキュリティと互換性を確認できたから採用する」という判断が重要です。今回の更新は、Analyze Text APIをより細かく制御できる可能性を広げる一方で、PIIや言語判定、レスポンススキーマに関する確認事項も増やします。まずは影響範囲を限定し、APIバージョン、ログ、マスキング、ジョブ処理の4点から確認を始めてください。

Azure
Azure REST API API移行 AnalyzeText Azure AI Services

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次