Azure SDK documentation update: Replace uuid dependency with crypto.randomUUID() in samples は、Azure SDK for JavaScript のサンプルコードで使われていた npm パッケージ uuid を外し、標準APIの crypto.randomUUID() に置き換える変更です。結論から言うと、Azure SDK本体の使い方が大きく変わる更新ではありません。対応が必要なのは、Azure SDKのサンプルをコピーして使っているプロジェクト、uuid をサンプル由来で入れているプロジェクト、Node.jsやブラウザの実行環境が古い可能性のあるプロジェクトです。対象PRでは、サンプルとドキュメント内のランダムID生成を crypto.randomUUID() に統一し、複数のサンプル用 package.json から uuid 依存を削除する内容が示されています。(GitHub)
Azure SDKのサンプルで何が変わるのか
今回の変更の中心は、ランダムなUUIDを生成するためだけに使われていた uuid npmパッケージを、Web Crypto APIの crypto.randomUUID() に置き換えることです。PRの説明では、uuid はサンプル内でランダムID生成のために使われており、同じ用途を標準APIで満たせるため追加依存が不要になる、と整理されています。(GitHub)
変更前の典型例は次のようなコードです。
import { v4 } from "uuid";
const id = v4();変更後は、追加インポートなしで次のように書けます。
const id = crypto.randomUUID();Node.jsのWeb Crypto APIは globalThis.crypto から利用できるため、読み手に実行環境を明確に伝えたい場合は次のように書くのも実務では分かりやすいです。Node.js公式ドキュメントでも、Web Crypto APIは globalThis.crypto または require("node:crypto").webcrypto からアクセスできると説明されています。(Node.js)
const id = globalThis.crypto.randomUUID();crypto.randomUUID() は、暗号学的に安全な乱数生成器を使ってv4 UUIDを生成するAPIです。MDNでは、ブラウザでは広く利用可能な機能として説明されており、HTTPSなどのセキュアコンテキストで使える点も明記されています。(MDN ウェブドキュメント)
変更のポイントを比較
| 確認項目 | 変更前 | 変更後 | 実務で見るべきポイント |
|---|---|---|---|
| UUID生成 | uuid パッケージの v4() を呼び出す | crypto.randomUUID() を呼び出す | ランダムなv4 UUID用途なら置き換えやすい |
| インポート | import { v4 } from "uuid" などが必要 | 原則として追加インポート不要 | 不要になったimport文を消さないとビルドエラーになる |
| 依存関係 | package.json に uuid が入る | サンプルでは uuid 依存を削除 | アプリ側で他用途に使っていないか確認してから削除する |
| 実行環境 | uuid がインストールされていれば動く | Web Crypto APIが使える環境が必要 | Node.jsのバージョン、ブラウザのHTTPS実行を確認する |
| 保守性 | サンプル実行のためだけに外部依存が増える | 標準APIで完結 | 依存パッケージ削減、lockfileの単純化につながる |
重要なのは、「uuid が不要になった」ではなく、「ランダムなv4 UUIDを生成するだけなら、サンプルでは uuid を使わず標準APIに寄せる」という点です。アプリケーション本体で名前空間ベースのUUID、旧環境対応、他のUUIDバージョンを使っている場合は、機械的に削除しないでください。
影響範囲：どのAzure SDKサンプルを確認すべきか
PR #38406では、複数のAzure SDK for JavaScriptサンプルと関連ドキュメントが対象になっています。PR本文では、Key Vault Admin、Digital Twins Core、Synapse Access Control REST、Cosmos DB、Event Hubs、React framework sample、Service Bus/Event Hubsのストレステストアプリなどが影響パッケージとして挙げられています。(GitHub)
| 対象 | 主な変更内容 | 確認すべき人 |
|---|---|---|
@azure/keyvault-admin samples v4 / v4-beta | サンプル内の名前やID生成を crypto.randomUUID() に変更 | Key Vault Adminのサンプルを元に管理スクリプトを作った人 |
@azure/digital-twins-core samples v1 / v2 | twin ID、model ID、telemetry message ID、route IDなどの生成を変更 | Digital TwinsのサンプルをPoCや検証環境に流用している人 |
@azure/synapse-access-control REST samples v1-beta | role assignment ID生成を変更 | Synapseの権限設定サンプルを使っている人 |
@azure/cosmos samples / MultiRegionWriteSample | item IDや競合シナリオ用ID生成を変更 | Cosmos DBのサンプルをベンチマークや検証に使っている人 |
@azure/event-hubs Express samples v5 / v6 / samples-express | request ID生成を変更 | Event HubsのExpressサンプルをWebアプリの雛形にしている人 |
| React framework sample | todo ID生成を変更 | Azure SDKのReactサンプルをフロントエンド学習用にコピーした人 |
@azure/service-bus / @azure/event-hubs stress test apps | package.json から uuid 依存を削除 | ストレステストアプリをローカルで動かしている人 |
レビュー概要では、60ファイルが変更対象として確認されており、TypeScript/JavaScriptサンプル、package.json、一部のmigration guideやドキュメントスニペットも含まれています。(GitHub)
なお、PR本文では「変更はサンプル・ドキュメントファイルであり、機能ロジックの変更ではない」と説明されています。執筆時点でPRはOpenとして表示されているため、実際に利用する際は対象ブランチやリポジトリ上の最新ファイルに反映済みか確認してください。(GitHub)
対応が必要なプロジェクト、不要なプロジェクト
今回のAzure SDK documentation updateで確認すべきなのは、Azure SDKを使っている全プロジェクトではありません。次の条件に当てはまる場合に、対応を検討します。
対応を検討すべきケース
次のいずれかに当てはまる場合は、コードと依存関係を確認してください。
- Azure SDKのJavaScript/TypeScriptサンプルをコピーして使っている
package.jsonにuuidがあり、用途がサンプル由来のID生成だけであるimport { v4 } from "uuid"やconst { v4 } = require("uuid")が残っている- Cosmos DB、Event Hubs、Digital Twinsなどのサンプルを検証環境や社内テンプレートに流用している
- ブラウザでサンプルコードを動かしており、HTTP環境や古いブラウザでの動作確認が必要
特に注意したいのは、サンプルから始めたPoCをそのまま本番寄りのコードに発展させているケースです。PoCでは「とりあえず動く」ことを優先しがちですが、後から依存関係を棚卸ししないと、実際には不要なパッケージが残り続けます。
対応しなくてよいケース
次のような場合は、無理に uuid を削除する必要はありません。
| ケース | 判断 |
|---|---|
アプリ本体で uuid を別用途に使っている | 削除しない。用途を確認してから判断する |
| ランダムv4以外のUUID生成が必要 | crypto.randomUUID() だけでは代替できない可能性がある |
| 古いNode.jsや特殊な実行環境を維持する必要がある | 標準APIの利用可否を確認してから移行する |
依存ライブラリが内部で uuid を使っている | アプリ側から直接削除する対象ではない |
| ID生成をテストで固定値にしたい | crypto.randomUUID() を直接呼ぶより、ID生成関数をラップした方がテストしやすい |
uuid を削除するかどうかは、「自分のコードで直接使っているか」「用途がランダムv4 UUIDだけか」「実行環境が crypto.randomUUID() に対応しているか」の3点で判断すると安全です。
移行手順：サンプル由来のuuid依存を外す
Azure SDKサンプルを元にしたコードを運用している場合は、次の順序で確認すると失敗しにくくなります。
依存と使用箇所を検索する
まず、uuid がどこで使われているかを確認します。rg が使える環境なら次のコマンドが便利です。
npx --yes rg "from ['\"]uuid['\"]|require\(['\"]uuid['\"]\)|uuid\.v4|v4\(\)" .v4() は他の関数名と衝突することがあるため、最終的には該当ファイルを開いて確認してください。検索結果がAzure SDKサンプル由来のID生成だけであれば、置き換え候補になります。
コードを置き換える
ES Modulesの例です。
// 変更前
import { v4 } from "uuid";
const roleAssignmentId = v4();// 変更後
const roleAssignmentId = crypto.randomUUID();CommonJSの例です。
// 変更前
const { v4: uuidv4 } = require("uuid");
const itemId = uuidv4();// 変更後
const itemId = crypto.randomUUID();Node.jsだけで動くアプリで、グローバルの crypto が利用できない実行環境を一時的に維持する場合は、node:crypto の randomUUID() を使う選択肢もあります。Node.js公式ドキュメントでは、node:crypto モジュールの crypto.randomUUID() はv4 UUIDを生成するAPIとして説明されており、追加されたバージョンも示されています。(Node.js)
import { randomUUID } from "node:crypto";
const id = randomUUID();ただし、Azure SDKサンプル更新の意図は、Node.jsとモダンブラウザで共通して使えるWeb Crypto APIに寄せることです。新しいサンプルに合わせるなら、まず crypto.randomUUID() または globalThis.crypto.randomUUID() を前提に実行環境を確認しましょう。
package.jsonからuuidを削除する
自分のコードで uuid を使っていないことを確認できたら、依存を削除します。
npm uninstall uuidpnpmを使っている場合は次のようにします。
pnpm remove uuidYarnの場合は次の通りです。
yarn remove uuid削除後は、lockfileも更新されているか確認します。
npm install
npm testCIを使っている場合は、ローカルだけでなくCI上でもテストを通してください。ローカルのNode.jsは新しくても、CIやデプロイ先のNode.jsが古いと crypto.randomUUID() が使えない可能性があります。
実行環境を確認する
Node.jsで確認する場合は、次のコマンドで globalThis.crypto.randomUUID が関数として見えるか確認できます。
node -e "console.log(process.version, typeof globalThis.crypto?.randomUUID)"期待する出力は、Node.jsのバージョンと function です。
v20.x.x functionブラウザで確認する場合は、開発者ツールのConsoleで次を実行します。
console.log(window.isSecureContext, typeof crypto.randomUUID);crypto.randomUUID() はブラウザではセキュアコンテキストで利用されるAPIです。MDNでは、ローカル開発で使われる http://localhost や http://127.0.0.1 は、ブラウザが信頼できるオリジンとして扱う場合があると説明されています。(MDN ウェブドキュメント)
移行時に失敗しやすいポイント
uuidを削除したのにimportが残っている
最も多いのは、package.json から uuid を削除したものの、コード側のimportが残っているケースです。
import { v4 } from "uuid";この状態でビルドすると、依存が解決できずエラーになります。削除前後で必ず検索をかけ、uuid の直接参照が残っていないか確認してください。
Node.jsの実行バージョンだけが古い
開発PCでは動いても、CI、Azure Functions、コンテナ、App Serviceなどの実行環境でNode.jsのバージョンが違うことがあります。Azure SDKのサンプル側ではNode.js 20以上を前提としているためポリフィル不要とされていますが、自分のアプリが同じ前提とは限りません。(GitHub)
確認すべき場所は次の通りです。
| 場所 | 確認内容 |
|---|---|
| ローカル | node -v |
| CI | GitHub Actions、Azure PipelinesなどのNode.js指定 |
| Docker | FROM node:20 などのベースイメージ |
| Azure実行環境 | App Service、Functions、Container AppsなどのNode.js runtime設定 |
| package.json | engines.node の指定 |
サンプルをコピーしただけの小さなコードでも、実行先のNode.jsが古いと動かないことがあります。
ブラウザでHTTP配信している
React framework sampleのようにブラウザで動くコードでは、crypto.randomUUID() がセキュアコンテキストで使えるかが重要です。ローカル開発では問題なくても、社内検証環境をHTTPで配信していると、環境によっては期待通りに動かない可能性があります。
本番やステージングではHTTPS化を前提にし、検証時には window.isSecureContext を確認しましょう。
テストでID生成が不安定になる
crypto.randomUUID() は毎回異なる値を返します。スナップショットテストや固定レスポンスを期待するテストでは、ID生成を直接呼ぶとテストが不安定になります。
その場合は、ID生成を小さな関数に切り出します。
export function createId(): string {
return crypto.randomUUID();
}テストではこの関数をモックします。
vi.mock("./createId", () => ({
createId: () => "00000000-0000-4000-8000-000000000000",
}));サンプルコードでは簡潔さが優先されますが、アプリケーション本体では「標準APIを直接あちこちで呼ばない」設計にした方が保守しやすくなります。
認証トークンの代わりに使ってしまう
crypto.randomUUID() は識別子の生成には便利ですが、認証や認可の根拠にするトークンとして安易に使うべきではありません。招待URL、パスワードリセット、セッション管理などでは、有効期限、保存方法、失効処理、漏えい時の影響範囲まで設計する必要があります。
Azure SDKサンプルでの用途は、リソース名、リクエストID、メッセージID、サンプルデータIDのような「一意な識別子」の生成です。セキュリティ設計そのものを置き換える変更ではありません。
Azure SDK利用者が取るべき確認チェックリスト
今回のAzure SDK documentation updateを受けて、実務では次の順で確認すると効率的です。
| 手順 | 作業 | 判断基準 |
|---|---|---|
| 1 | uuid の使用箇所を検索する | Azure SDKサンプル由来のランダムID生成だけか |
| 2 | crypto.randomUUID() に置き換える | v4 UUID生成だけなら置き換えやすい |
| 3 | package.json から uuid を削除する | 他用途で使っていなければ削除する |
| 4 | lockfileを更新する | package-lock.json、pnpm-lock.yaml、yarn.lock を確認 |
| 5 | Node.jsバージョンを確認する | ローカル、CI、Azure実行環境をそろえる |
| 6 | ブラウザ実行環境を確認する | HTTPSまたは信頼できるローカル環境で動くか |
| 7 | テストを修正する | ランダムIDでテストが不安定にならないか |
特に、Azure SDKサンプルを社内テンプレートとして配布している場合は、テンプレート側で uuid を削除しておくと、新規プロジェクトに不要な依存を持ち込まずに済みます。
今回の変更をどう評価すべきか
今回の uuid から crypto.randomUUID() への置き換えは、派手な新機能ではありません。しかし、サンプルコードの品質としては意味のある変更です。
サンプルコードは、多くの開発者にとって実装の出発点になります。そこで不要な外部依存が含まれていると、コピー先のアプリにもそのまま残りやすくなります。今回のように、標準APIで十分な処理を標準APIへ寄せる方針は、依存管理、セキュリティレビュー、サンプルの読みやすさの面でメリットがあります。
一方で、アプリケーション側では「サンプルが変わったから全部置き換える」と考えるのは危険です。置き換えてよいのは、用途がランダムなv4 UUID生成であり、実行環境が crypto.randomUUID() に対応している場合です。古いNode.js、HTTP配信のブラウザ環境、特殊なテスト環境では、事前確認が欠かせません。
まずは自分のプロジェクトで uuid の直接利用を検索し、用途を分類してください。サンプル由来のID生成だけなら、crypto.randomUUID() へ移行し、依存関係を削除するのが次のアクションです。逆に、UUIDの別バージョンや互換性のために使っているなら、無理に削除せず、目的に合った実装を維持しましょう。
コメント