Azure REST APIの「Azure REST API documentation update: [Document] fix Typespec 2026-05-15-preview」は、Azure REST API全体の仕様変更ではなく、主にAzure AI LanguageのLanguageAnalyzeDocumentsデータプレーンAPIに関するTypeSpec／OpenAPIドキュメント更新として確認すべき内容です。特に、api-version=2026-05-15-previewを使う予定がある開発者、SDK生成やREST API仕様差分を追っているチーム、ドキュメント要約・PII検出を組み込んでいるサービス担当者は、影響範囲を早めに確認しておくべきです。
結論から言うと、安定版の2026-05-01だけを使っている本番環境では、すぐにコードを書き換える必要はない可能性が高いです。一方で、プレビュー版2026-05-15-previewを検証中、またはTypeSpecからSDKやAPI仕様書を生成している場合は、要約タスク、PIIリダクション、モデル名、C#クライアント名、stringIndexTypeまわりの挙動確認が必要です。PRはDraftとして表示され、Cognitive Services、data-plane、TypeSpec関連の更新として扱われています。(GitHub)
Azure REST APIの今回の更新は何を対象にしているのか
今回の更新は、Azure REST API仕様リポジトリのPR「[Document] fix Typespec 2026-05-15-preview」に関するものです。PR本文自体は汎用的なテンプレートに近く、変更内容を理解するにはPRの差分と対象ファイルを見る必要があります。差分では、specification/cognitiveservices/data-plane/LanguageAnalyzeDocuments/配下のTypeSpecファイルと、preview/2026-05-15-preview/analyzedocuments.jsonなどのOpenAPIファイルが対象になっています。(GitHub)
Azure REST API specsの設定では、LanguageAnalyzeDocumentsの現在のプレビューリリースとして2026-05-15-preview、安定版として2026-05-01が示されています。つまり、今回の変更は「Azure REST API全体の仕様が変わった」というより、Azure AI Languageのドキュメント分析APIにおけるプレビュー仕様の整備・修正として読むのが適切です。(GitHub)
まず押さえるべき変更点
| 確認項目 | 内容 | 実務上の見方 |
|---|---|---|
| 対象API | LanguageAnalyzeDocumentsのデータプレーンAPI | Azure AI Languageのドキュメント分析・要約・PII処理を使うチームが主な対象 |
| 対象バージョン | 主に2026-05-15-preview | プレビュー利用中、または検証予定なら差分確認が必要 |
| 関連する安定版 | 2026-05-01 | 安定版だけを使う本番環境では、即時変更より監視が中心 |
| 変更ファイル | TypeSpecのclient.tsp、common.models.tsp、pii.entity.recognition.tsp、summarization.tspなど | SDK生成、型名、ドキュメント記述に影響しやすい |
| OpenAPI出力 | preview/2026-05-15-preview/analyzedocuments.json | REST直接利用やAPIクライアント自作時に確認すべき |
| SDK影響 | .NET、Python SDK生成設定が関連 | 自動生成クライアントやラッパーの型名差分に注意 |
対象ファイルには、クライアント名の調整、要約関連モデルの追加・復帰、PIIリダクション関連の命名・説明修正、StringIndexTypeの説明修正などが含まれます。C#向けにはDocumentAnalysisClient、PiiEntityRecognitionAction、EntityMaskRedactionPolicy、TargetReferenceなどの名称調整が見えるため、生成コードを利用している場合はビルド時の型名変更として表面化する可能性があります。(GitHub)
対応が必要な人、様子見でよい人
この更新で最初に判断すべきなのは、自社システムが2026-05-15-previewを使っているかどうかです。Azure REST APIではapi-versionを明示して呼び出すため、利用中のバージョンが違えば影響度も変わります。
| 利用状況 | 対応優先度 | 確認すべきこと |
|---|---|---|
api-version=2026-05-15-previewを検証中 | 高 | リクエスト／レスポンスのモデル名、要約タスク、PIIリダクション設定を確認 |
| TypeSpecからSDKやOpenAPIを生成している | 高 | 生成後の型名・クライアント名・operation名の差分を確認 |
| C# SDKの生成コードやラッパーを使う予定 | 高 | DocumentAnalysisClientなどの名称変更が既存コードに影響しないか確認 |
| REST APIを直接呼び出している | 中 | エンドポイント、api-version、JSONスキーマ、長時間実行ジョブの扱いを確認 |
2026-05-01の安定版のみを本番利用 | 低〜中 | 直ちに移行せず、プレビュー仕様の安定化を監視 |
| Azure AI Languageの要約機能を新規採用予定 | 中 | プレビュー仕様だけでなく、サービスの将来方針も確認 |
PRページでは、mainブランチにマージされるAPIは出荷済みとして扱われる旨の説明があり、同時に調査時点ではDraft状態やTypeSpec Validationの失敗表示も確認できます。プレビュー版を採用する場合は、PRのタイトルや公開日だけで判断せず、マージ状態、検証結果、最新コミット、公式ドキュメントの更新をセットで確認することが重要です。(GitHub)
2026-05-15-previewで注目すべきAPI仕様
2026-05-15-previewのOpenAPIでは、/analyze-documents/jobsに対するPOSTでドキュメント分析ジョブを作成し、/analyze-documents/jobs/{jobId}で状態や結果を取得する形が示されています。これは長時間実行操作として扱われ、POSTの成功時には202 AcceptedとOperation-Locationが返る構成です。(GitHub)
POST {Endpoint}/language/analyze-documents/jobs?api-version=2026-05-15-preview非同期処理のAPIでは、送信後すぐに結果が返るのではなく、ジョブIDを使って状態を確認します。Azure AI Languageの非同期処理では、POSTでジョブを作成し、GETで結果を取得する流れが説明されています。結果が保持される期間にも制限があるため、運用では「結果取得のリトライ」「期限内の保存」「失敗時の再実行」を設計に含める必要があります。(Microsoft Learn)
要約タスクの追加・復帰を確認する
今回の差分で特に目立つのが、ドキュメント要約に関するTypeSpecの更新です。ExtractiveSummarizationとAbstractiveSummarizationのタスクや結果モデルに、2026-05-15-preview向けの追加指定が見えます。抽出型要約は重要文を抜き出す方式、抽象型要約は内容を再構成して短い要約文を生成する方式として使い分けます。(GitHub)
| 要約方式 | 向いている用途 | 確認ポイント |
|---|---|---|
| Extractive Summarization | 契約書、議事録、FAQなどから重要文を抽出したい場合 | sentenceCount、並び順、オフセット情報 |
| Abstractive Summarization | 長文文書の概要を自然な文章でまとめたい場合 | 生成される要約文、根拠範囲、業務上の許容精度 |
| Native document summarization | PDFやDOCXなどの文書を扱いたい場合 | 対応形式、ファイルサイズ、Blob権限、非同期処理 |
Microsoft Learnでは、ネイティブドキュメント要約の対象形式として.txt、.pdf、.docxが示されています。一方で、スキャンPDFや画像内テキスト、スキャンされた表は対象外とされています。実務では「PDFだから処理できる」と決めつけず、テキスト抽出可能なPDFか、画像化されたPDFかを事前に判定する必要があります。(Microsoft Learn)
SummarySpanとオフセット処理は日本語環境で特に注意
差分では、要約結果の文脈情報に関するモデルとしてSummarySpanが確認できます。SummarySpanはoffsetとlengthを持ち、どの範囲が要約に関連するかを表す情報として扱われます。ここで重要なのが、stringIndexTypeによってオフセットと長さの解釈が変わる点です。(GitHub)
StringIndexTypeには、TextElements_v8、UnicodeCodePoint、Utf16CodeUnitなどの値があり、説明文も修正されています。日本語、絵文字、結合文字を含む文書では、単純な文字数カウントとAPIの返すoffset／lengthが一致しないことがあります。画面ハイライト、引用範囲表示、監査ログを実装している場合は、ここを軽視すると「要約の根拠として表示する範囲がずれる」問題が起きます。(GitHub)
日本語文書でテストすべき例
| テスト文書 | 起きやすい問題 | 確認方法 |
|---|---|---|
| 日本語の句読点を含む契約書 | 文単位の抽出位置が想定とずれる | API結果のoffsetと画面表示を照合 |
| 絵文字を含む問い合わせ本文 | 文字数計算が実装言語ごとにずれる | stringIndexTypeごとにテスト |
| 英数字と日本語が混在するFAQ | ハイライト位置がずれる | フロントエンドの切り出し処理を確認 |
| 改行や箇条書きが多い議事録 | 抽出文の範囲表示が崩れる | 元文書と結果の差分を確認 |
特に.NET、JavaScript、Pythonなど複数言語で同じAPI結果を扱うシステムでは、サーバー側とクライアント側で文字列の数え方が違うことがあります。APIの返すoffsetをそのままUIに渡すのではなく、選択したstringIndexTypeに合わせて切り出し処理を統一してください。
PIIリダクション関連の変更で見るべきポイント
PII検出・リダクションまわりでは、EntityMaskRedactionPolicyなどの命名調整や、RedactionPolicyKindの説明修正が確認できます。差分では、markerMaskやsyntheticReplacementが2026-05-15-previewで追加される指定も見えます。(GitHub)
PIIリダクションは、単に「個人情報を消す」だけではありません。監査ログ、問い合わせ管理、顧客サポート、文書検索などでは、以下のように用途によって適切なマスク方式が変わります。
| 用途 | 向いている考え方 | 注意点 |
|---|---|---|
| 顧客対応ログの保管 | 個人情報を確実に隠す | 元文書を別経路で保存していないか確認 |
| オペレーター画面表示 | 必要最小限の情報だけ表示 | 過剰マスクで業務が止まらないか確認 |
| 監査・分析 | 種別が分かる形でマスク | 個人を再識別できる情報が残らないか確認 |
| 検索インデックス投入 | 検索対象からPIIを除外 | インデックス作成前にマスク処理を行う |
今回のようなTypeSpec上の名称修正は、RESTのJSONだけを見ていると小さな変更に見えることがあります。しかし、SDK生成後の型名、設定名、ドキュメント表示名に反映されると、ラッパーコードやサンプルコードの修正が必要になる場合があります。
SDK生成・クライアントコードで確認すべき差分
Azure REST API仕様を使ってSDKを生成しているチームは、今回の更新を「ドキュメント修正」だけで済ませない方が安全です。PR差分では、C#向けのクライアント名やモデル名に関するカスタマイズが複数確認できます。たとえば、AnalyzeDocumentsをDocumentAnalysisClientとして扱う指定や、tasksをActionsへ、analysisInputをDocumentsInputへ寄せるような名称調整が含まれています。(GitHub)
次のような文字列がプロジェクト内にある場合は、影響を受ける可能性があります。
rg "2026-05-15-preview|ExtractiveSummarization|AbstractiveSummarization|SummaryContext|SummarySpan|PiiEntityRecognition|EntityMaskRedactionPolicy|stringIndexType" .特に注意したいのは、既存コードが古いモデル名に依存しているケースです。生成コードそのものは更新できても、アプリケーション側で古い型名を参照しているとビルドエラーになります。また、JSONのプロパティ名とSDK上の型名は必ずしも同じではないため、REST呼び出しとSDK利用を混在させているチームは、両方の差分を分けて確認してください。
移行前に確認するチェックリスト
プレビューAPIへの移行や検証を始める前に、次の順序で確認すると手戻りを減らせます。
| 手順 | 確認内容 | 判断基準 |
| -: | ———————– | ——————————— |
| 1 | 現在使っているapi-versionを確認 | 2026-05-15-previewでなければ即時影響は限定的 |
| 2 | REST直接利用かSDK利用かを分類 | SDK利用なら生成後の型名差分も確認 |
| 3 | 要約タスクを使うか確認 | Extractive／Abstractiveのどちらを使うか決める |
| 4 | PIIリダクション設定を確認 | マスク方式が業務要件と合うか検証 |
| 5 | stringIndexTypeを固定 | 日本語・絵文字・改行を含む文書でテスト |
| 6 | 非同期ジョブの運用を確認 | 結果取得、期限、失敗時再実行を設計 |
| 7 | PRと公式ドキュメントの状態を確認 | Draft、検証結果、マージ状況を採用前に見る |
| 8 | 本番投入前に小規模データで比較 | 旧バージョンと結果差分を記録 |
LanguageAnalyzeDocumentsのREADMEでは、プレビュー版2026-05-15-previewと安定版2026-05-01の入力ファイルが分けて定義されています。検証環境ではプレビュー、本番では安定版という構成を取る場合、環境変数や設定ファイルでapi-versionが混在しないように管理してください。(GitHub)
よくある失敗と回避策
PRタイトルだけを見て「ドキュメント修正だから影響なし」と判断する
今回のPRタイトルには[Document]とありますが、差分にはTypeSpecのクライアント名、モデル名、要約タスク、PII関連の変更が含まれています。ドキュメント表記の修正であっても、SDK生成や型定義に関わる場合はコード側に影響することがあります。(GitHub)
プレビュー版を安定版と同じ感覚で使う
プレビュー版は早期アクセスの位置づけであり、一般提供前に機能や仕様が変わる可能性があります。Azure AI Languageのドキュメントでも、プレビューリリースはGA前に機能やアプローチ、プロセスが変わる可能性があると説明されています。(Microsoft Learn)
本番で使う場合は、プレビュー版でしか使えない機能が本当に必要か、代替手段があるか、仕様変更時に追随できる体制があるかを確認してください。
オフセット処理を英語文書だけで検証する
日本語、絵文字、全角記号を含む文書では、オフセットと文字列切り出しの問題が見つかりやすくなります。要約結果やPII検出結果を画面上でハイライトする場合、英語だけのテストでは不十分です。stringIndexTypeを明示し、日本語の実データに近い文書で確認してください。(GitHub)
要約機能の将来計画を確認しない
Azure AI Languageの要約機能については、Microsoft Learnで2029年3月31日のリタイア予定と、Microsoft Foundryモデルへの移行推奨が示されています。既存機能の検証と同時に、中長期のアーキテクチャとしてどのサービスを採用するかも検討しておくべきです。(Microsoft Learn)
実務でのおすすめ対応
今回のAzure REST API documentation updateを受けて、まず行うべきことは大きく3つです。
1つ目は、利用中または検証中のapi-versionを確認することです。2026-05-15-previewを使っていない場合は、慌てて修正するより、今後のプレビュー仕様として監視する対応で十分な場合があります。
2つ目は、SDK生成や型定義に関わるチームが差分を確認することです。特にC#クライアント名、PIIアクション名、要約結果モデル、SummarySpanのようなモデル名は、生成コードやサンプルコードに影響しやすい部分です。(GitHub)
3つ目は、日本語文書での動作確認です。Azure REST APIの仕様上は小さな名称変更に見えても、実際のアプリケーションでは「要約の根拠範囲がずれる」「PIIマスク後の表示が読みにくい」「SDK更新後に型名が変わる」といった問題として現れます。
まとめ：今すぐ確認すべきこと
今回の更新は、Azure REST APIの中でもAzure AI LanguageのLanguageAnalyzeDocumentsに関する2026-05-15-preview仕様を確認すべき内容です。安定版だけを使っている本番環境では即時対応の必要性は限定的ですが、プレビュー版、TypeSpec、SDK生成、要約、PIIリダクションに関わるチームは早めに差分を確認してください。
次に取るべき行動は、プロジェクト内で2026-05-15-preview、ExtractiveSummarization、AbstractiveSummarization、SummarySpan、PiiEntityRecognition、stringIndexTypeを検索し、該当箇所があれば検証環境で旧仕様との差分を確認することです。プレビューAPIを採用する場合は、PRのマージ状態と公式ドキュメントの更新状況を見ながら、SDK生成、REST呼び出し、UI表示、ログ保存まで含めて確認しましょう。
コメント