Azure SDKのBeta Activation変更案を解説：@azure/search-documentsで確認すべき影響と移行ポイント

2026年5月5日に更新・クローズされた Azure SDK for JavaScript の PR #37650 は、@azure/search-documents に Beta Activation という設計パターンを導入し、プレビュー API を enableBeta() の呼び出し後だけ見えるようにする提案です。結論から言うと、現時点で確認すべきなのは「すぐコードを書き換えること」ではなく、@azure/search-documents の利用箇所、プレビュー API の依存、serviceVersion / apiVersion の指定、TypeScript の型エラー発生箇所を洗い出すことです。PR は 2026年5月5日に Closed となっており、正式リリースへの反映有無はパッケージの CHANGELOG と実際のインストール済みバージョンで確認する必要があります。(GitHub)

Azure AI Search の JavaScript クライアントである @azure/search-documents は、検索クエリ、インデックス管理、ドキュメント更新、インデクサー、スキルセットなどを扱う SDK です。今回の変更案は、その中でも主に SearchIndexClient と、プレビュー機能を含む API サーフェスの見せ方に関わります。(Microsoft Learn)

Azure SDKのBeta Activationとは何か

Beta Activation は、安定版 API とプレビュー API を同じパッケージ内に持たせつつ、通常の利用者にはプレビュー API を見せないための仕組みです。

PR の説明では、これまで TypeSpec から生成される SDK に安定版操作とプレビュー操作が混在する場合、安定版リリース前にプレビュー操作を手作業で取り除き、プレビューリリースでは戻す必要があったとされています。この作業はミスが起きやすく、自動化の妨げにもなるため、enableBeta() によって明示的にプレビュー機能へオプトインする形が提案されています。(GitHub)

イメージとしては、次のような使い分けです。

import { SearchIndexClient, AzureKeyCredential } from "@azure/search-documents";
import type { SearchIndexClientWithBeta } from "@azure/search-documents/beta";

const client = new SearchIndexClient(
  endpoint,
  new AzureKeyCredential(apiKey),
);

// 通常の安定版利用
const indexes = client.listIndexes();

// プレビューAPIを使う場合は明示的に有効化
const betaClient: SearchIndexClientWithBeta = client.enableBeta();

const knowledgeBase = await betaClient.createKnowledgeBase({
  name: "example-knowledge-base",
});

重要なのは、enableBeta() を呼んだコードだけがプレビュー API を扱うという点です。安定版だけを使うアプリケーションでは、IDE の補完や TypeScript の型定義にプレビュー API が出てこないため、誤って未成熟な機能に依存しにくくなります。

何が変わるのか

PR #37650 で示された主な変更点は、次のとおりです。

変更点	内容	開発者が見るべきポイント
enableBeta() の追加	SearchIndexClient にプレビュー API を有効化するメソッドを追加	呼び出し位置を限定し、安定版コードと混ぜない
./beta サブパスの追加	@azure/search-documents/beta から beta 用の型を export	beta 型を通常の公開 API に漏らさない
beta 型の分離	BetaSearchIndex、BetaIndexIterator などを beta 側に配置	SearchIndex と BetaSearchIndex の差分を確認する
API バージョンの切り替え	明示指定がない場合、enableBeta() が preview API version へ切り替える設計	serviceVersion / apiVersion を固定しているコードを確認する
戻り値型による型拡張	assertion narrowing ではなく、SearchIndexClientWithBeta を返す方式	client.enableBeta() の戻り値を必ず変数に受ける

PR では、enableBeta() が preview API version への切り替え、プレビュー操作の付与、より広い型への変換を行うと説明されています。また、beta 型は ./beta サブパスに置かれ、通常利用者の補完に出ないようにする方針です。(GitHub)

誰が対応を確認すべきか

今回の Azure SDK documentation update は、すべての Azure SDK 利用者に同じ影響があるわけではありません。特に確認が必要なのは、@azure/search-documents を TypeScript で使い、インデックス管理やプレビュー API に近い機能を利用しているチームです。

利用状況	影響度	確認すべきこと
SearchClient で検索クエリだけを実行している	低	パッケージ更新後に tsc --noEmit を通す
SearchIndexClient でインデックスを作成・更新している	中	listIndexes()、getIndex()、createIndex() の戻り値型を確認
Knowledge Base / Knowledge Source 系 API を使っている	高	その API が安定版か beta 側かを確認
alias 管理や index stats を使っている	中〜高	enableBeta() 必須になっていないか確認
SDK をラップした社内ライブラリを公開している	高	beta 型を公開インターフェースに混ぜていないか確認

@azure/search-documents は、検索、インデックス管理、インデクサー、スキルセットなど幅広い操作を担います。そのため、単に検索画面からクエリを投げるだけのアプリと、管理画面や運用バッチでインデックスを操作するアプリでは、影響範囲が大きく異なります。(Microsoft Learn)

移行前に確認したいチェックリスト

正式なリリースに反映された場合に備え、まずは次の順番で確認すると安全です。

インストール済みバージョンとCHANGELOGを確認する

まず、実際に利用している @azure/search-documents のバージョンを確認します。

npm ls @azure/search-documents

CI や本番ビルドで使う lockfile も確認してください。

cat package-lock.json | grep "@azure/search-documents"

PR #37650 は 2026年5月5日に Closed されていますが、Closed された PR と npm パッケージへの反映は同義ではありません。CHANGELOG では 2026年5月1日に 13.0.0 が記録され、KnowledgeRetrievalClient や KnowledgeBase 管理 API の追加、安定版への昇格に伴う変更が記載されています。一方で、PR の内容を適用済みと判断するには、該当バージョンの API 定義やリリースノートを直接確認する必要があります。(GitHub)

previewに近いAPIの利用箇所を検索する

次に、影響を受けやすいメソッドやプロパティを検索します。

grep -R "createKnowledgeBase\|createOrUpdateKnowledgeBase\|getKnowledgeBase\|listKnowledgeBases" src test
grep -R "createKnowledgeSource\|getKnowledgeSourceStatus\|listKnowledgeSources" src test
grep -R "listAliases\|createAlias\|getIndexStatsSummary" src test
grep -R "permissionFilterOption\|purviewEnabled" src test

これらが見つかった場合は、次の観点で確認します。

確認項目	判断基準
安定版として使っているか	公式の API reference または CHANGELOG で安定版に含まれるか確認
preview API として使っているか	enableBeta() が必要になる可能性を想定
型を明示しているか	SearchIndex、BetaSearchIndex、独自 interface の差分を確認
ラップしているか	社内 SDK や共通関数の戻り値型に beta 型が漏れていないか確認

TypeScriptのビルドで差分を検出する

SDK の API サーフェス変更は、実行時よりも TypeScript の型エラーとして先に見つかることが多いです。

npx tsc --noEmit

特に次のようなエラーは見逃さないでください。

Property 'createKnowledgeBase' does not exist on type 'SearchIndexClient'.
Property 'purviewEnabled' does not exist on type 'SearchIndex'.
Type 'SearchIndex' is not assignable to type 'BetaSearchIndex'.

このようなエラーが出た場合、単に any で逃げるのは避けるべきです。preview API を本当に使う必要があるのか、安定版 API で代替できるのか、beta 用のコードパスとして分離するのかを判断しましょう。

enableBeta()を使う場合の実装方針

enableBeta() が正式に利用可能になった場合は、安定版クライアントと beta クライアントを同じ関数で曖昧に返さないことが重要です。

悪い例は、共有の factory 関数で条件分岐だけして同じ変数名で返す書き方です。

export function createIndexClient(useBeta: boolean) {
  const client = new SearchIndexClient(endpoint, credential);

  if (useBeta) {
    return client.enableBeta();
  }

  return client;
}

この書き方では、呼び出し側で「安定版なのか beta なのか」が分かりにくくなります。型も広がりやすく、preview API がアプリ全体に漏れます。

実務では、次のように明確に分ける方が安全です。

export function createStableSearchIndexClient() {
  return new SearchIndexClient(endpoint, credential, {
    serviceVersion: stableServiceVersion,
  });
}

export function createBetaSearchIndexClient() {
  return new SearchIndexClient(endpoint, credential).enableBeta();
}

さらに、beta 型の import は beta 用の実装ファイルに閉じ込めます。

import type { SearchIndexClientWithBeta } from "@azure/search-documents/beta";

アプリケーション全体で beta 型を re-export すると、後から安定版へ戻すときに影響範囲が広がります。社内ライブラリを作っている場合は、beta 型を公開 API に含めず、内部実装で閉じるのが無難です。

serviceVersionとapiVersionの確認は必須

PR の説明では、enableBeta() はユーザーが明示的に API version を指定していない場合に preview version へ切り替えるとされています。つまり、既に serviceVersion や apiVersion を固定しているコードでは、enableBeta() を呼んでも期待した preview API に接続されない可能性があります。(GitHub)

確認すべきコードは次のような箇所です。

grep -R "serviceVersion\|apiVersion" src config test

チェック観点は次の3つです。

確認項目	注意点
安定版APIを明示しているか	beta API 呼び出しと組み合わせると不整合が起きる可能性がある
環境変数で API version を切り替えているか	dev / staging / production で挙動が変わる
テストだけ preview version になっていないか	本番の安定版コードパスが未検証になる

レビューコメントでは、安定版のテストが preview version に寄ってしまい、安定版コードパスが十分に検証されない懸念も指摘されていました。beta を使う場合でも、安定版テストと beta テストは分けておくべきです。(GitHub)

注意したい破壊的変更の見え方

PR のレビューでは、SearchIndexClient から複数の public メソッドが enableBeta() 側に移動すること、SearchIndex から permissionFilterOption と purviewEnabled が外れること、SearchIndexClientWithBeta の export 位置、enableBeta() が readonly プロパティを変更する可能性などが指摘されました。(GitHub)

ただし、この点は慎重に読む必要があります。後続の修正 PR では、API report 上で @beta TSDoc が使われていないため、レビュー自動化が beta-only API の削除を誤って破壊的変更として検出していた、という説明もあります。つまり、過去のレビューコメントだけを見て「確定した breaking change」と判断するのは危険です。実際の GA ベースライン、利用中のバージョン、リリースノートを照合して判断する必要があります。(GitHub)

実務上は、次のように扱うのが現実的です。

状況	判断
現在の安定版で問題なく動いている	急いで enableBeta() を追加しない
preview 機能を使う予定がある	beta 用ブランチや検証環境で先に試す
SDK 更新で型エラーが出た	any ではなく、安定版 API と beta API の境界を見直す
ライブラリを外部公開している	beta 型を公開契約に含めない
本番で API version を固定している	enableBeta() の挙動と矛盾しないか確認する

よくある失敗パターン

enableBeta()の戻り値を使わない

enableBeta() は戻り値の型で beta API を表現する設計です。そのため、戻り値を捨てると TypeScript 上は安定版クライアントのまま扱われる可能性があります。

const client = new SearchIndexClient(endpoint, credential);

client.enableBeta();

// この形では型が広がらない可能性がある
await client.createKnowledgeBase(kb);

次のように、beta 用の変数を明示しましょう。

const betaClient = client.enableBeta();

await betaClient.createKnowledgeBase(kb);

安定版とbeta版で同じクライアントを使い回す

レビューでは、enableBeta() が元のインスタンスに副作用を与える可能性が指摘されました。正式実装でどう扱われるかは確認が必要ですが、設計上は安定版用と beta 用のクライアントを分けておく方が安全です。(GitHub)

const stableClient = new SearchIndexClient(endpoint, credential);
const betaClient = new SearchIndexClient(endpoint, credential).enableBeta();

beta型を通常のAPIレスポンスとして公開する

たとえば、社内 API の戻り値に BetaSearchIndex をそのまま使うと、後から stable に戻すときに利用側まで修正が必要になります。

// 避けたい例
export async function listIndexes(): Promise<BetaSearchIndex[]> {
  // ...
}

外部に出す型は独自 DTO に変換し、SDK の beta 型を隠す方が保守しやすくなります。

type IndexSummary = {
  name: string;
  fieldCount: number;
  purviewEnabled?: boolean;
};

今取るべきアクション

今回の Azure SDK の Beta Activation パターンは、プレビュー API を安全に扱うための方向性として重要です。一方で、PR #37650 は Closed されており、実際の利用可否はリリース済みパッケージと CHANGELOG で確認する必要があります。(GitHub)

まずやるべきことは、次の3つです。

1つ目は、npm ls @azure/search-documents で利用バージョンを確認すること。2つ目は、SearchIndexClient、Knowledge Base、Knowledge Source、alias、index stats、permissionFilterOption、purviewEnabled の利用箇所を検索すること。3つ目は、SDK 更新後に npx tsc --noEmit と安定版・beta 版を分けたテストを実行することです。

プレビュー機能を使っていないチームは、焦って対応する必要はありません。ただし、Azure AI Search 周りは生成 AI、ベクトル検索、Knowledge Base などの追加が速い領域です。SDK 更新時に「型エラーが出たら直す」ではなく、「安定版 API と preview API の境界を設計として分ける」ことが、今後の移行コストを下げる最も実用的な対策になります。