Azure REST API documentation update のうち、Storage の AccessPolicy.start / AccessPolicy.expiry に関する今回の変更は、Azure Storage のRESTエンドポイントそのものを変える更新ではありません。ポイントは、Blob Storage と Queue Storage の TypeSpec 定義で、Python向けクライアント生成時にも start / expiry を string として扱えるように @@alternateType の適用範囲が広がったことです。PythonでAzure StorageのSASやStored Access Policyを扱うチームは、日時フィールドを datetime 前提で固定していないか、テストや型チェックを確認しておくべきです。関連PRは2026年5月4日にAzure REST API Specsのmainへマージされ、対象ファイルは Microsoft.BlobStorage/client.tsp と Microsoft.QueueStorage/client.tsp です。(GitHub)
今回のAzure REST API documentation updateで変わったこと
今回の更新内容は、Storage領域の AccessPolicy.start と AccessPolicy.expiry に対する @@alternateType 指定を、従来の "javascript" から "javascript, python" に広げるものです。対象は Blob Storage と Queue Storage です。(GitHub)
変更前後を整理すると、次のようになります。
| 項目 | 変更前 | 変更後 |
|---|---|---|
| 対象サービス | Blob Storage、Queue Storage | Blob Storage、Queue Storage |
| 対象フィールド | AccessPolicy.start / AccessPolicy.expiry | 同じ |
@@alternateType のスコープ | javascript | javascript, python |
| Pythonへの影響 | utcDateTime として扱われる可能性があった | Python向け生成でも string として扱える |
| REST APIのワイヤ仕様 | 変更なし | 変更なし |
ここで重要なのは、Azure Storageの認可仕様やSASの有効期限ルールが変わったわけではないという点です。変更の中心は、Azure REST API SpecsからSDKやクライアント定義を生成する際の型表現です。
@@alternateType は、TypeSpec上のモデルプロパティなどに対して、生成されるクライアント側で別の型を適用するためのデコレーターです。対象言語のスコープも指定でき、"python" や "python, java" のように複数言語をカンマ区切りで指定できます。(Azure)
なぜPythonもstring扱いにする必要があるのか
PRの説明では、Blob StorageとQueue Storageの AccessPolicy.start / AccessPolicy.expiry は rfc3339-fixed-width、つまりサブ秒精度を含む固定幅のRFC3339形式でエンコードされるとされています。Pythonのエミッターでは、これらを utcDateTime としてモデル化すると精度が失われる問題があり、JavaScriptで既に行われていた string への代替型指定をPythonにも広げた、という背景です。(GitHub)
実務上は、次のように理解すると判断しやすくなります。
| 観点 | 説明 |
|---|---|
| サービス側の意味 | start はアクセス許可が有効になる時刻、expiry は無効になる時刻 |
| 問題になりやすい点 | Python側で日時型に変換する過程で、サブ秒精度や文字列表現が変わる可能性 |
| 今回の修正意図 | Python SDK生成時にも、日時値を文字列として保持できるようにする |
| 期待される効果 | 生成コードの型表現が実際のRESTエンコードに近づき、精度劣化を避けやすくなる |
Azure StorageのSASでは、アクセスできるリソース、権限、有効期間を細かく制御できます。Stored Access Policyを使う場合、開始時刻、終了時刻、権限をポリシー側に定義し、関連付けられたSASの動作を後から変更・取り消しできるため、start / expiry は単なる日時フィールドではなく、認可制御に直結する値です。(Microsoft Learn)
影響を受ける可能性が高いチーム
今回のAzure REST API documentation updateで特に確認したいのは、Azure StorageをPythonで扱う開発チームです。ただし、すべての利用者が即座にコード修正を迫られるわけではありません。
| 対象者 | 対応優先度 | 確認すべきこと |
|---|---|---|
| Azure REST API SpecsからPython SDKやクライアントを生成している | 高 | 再生成後の AccessPolicy.start / expiry の型差分 |
azure-storage-blob / azure-storage-queue でStored Access Policyを操作している | 中〜高 | datetime 固定の実装やテストがないか |
| Blob / QueueのSAS有効期間を自動生成している | 中 | 文字列・日時変換で精度やタイムゾーンが変わらないか |
| JavaScriptのみ利用している | 低 | 既存のJavaScriptスコープは維持されているため、基本的には影響小 |
| REST APIを直接HTTPで呼び出している | 低 | ワイヤ形式自体は変更されていないため、既存リクエストの見直しは限定的 |
特に注意したいのは、Pythonコードで次のような前提を置いている場合です。
AccessPolicy.startとAccessPolicy.expiryは必ずdatetimeとして返る- JSON化やログ出力の前に、必ずPythonの日時型へ変換する
- マイクロ秒やミリ秒を含む文字列を、テストで単純な日時比較に置き換えている
Z、タイムゾーン、サブ秒の桁数を正規化してしまう共通処理がある
Microsoft Learn上のPython向けBlob Storageの AccessPolicy では、expiry と start は datetime または str を受け取れる形で説明されています。Queue Storage側のドキュメントでも、関連する日時引数は datetime または str として案内されています。つまり、実装側でも「日時型だけ」と決め打ちせず、文字列を扱える設計にしておくのが安全です。(Microsoft Learn)
移行・設定確認で見るべきポイント
今回の変更は、ストレージアカウントの設定変更を求めるものではありません。確認すべき対象は、主にコード生成、型定義、テスト、日時の正規化処理です。
Pythonの型チェックを確認する
まず、AccessPolicy.start / AccessPolicy.expiry を受け取る関数やテストヘルパーで、型を datetime に固定していないか確認します。
避けたい例は、次のような実装です。
from datetime import datetime
def format_policy_expiry(expiry: datetime) -> str:
return expiry.isoformat()この実装は、値が文字列で渡された場合に壊れます。更新後の生成コードやSDKの型表現に追随するなら、少なくとも datetime と str の両方を受けられるようにしておくと安全です。
from datetime import datetime, timezone
from typing import Optional, Union
AccessPolicyTime = Union[datetime, str]
def normalize_policy_time(value: Optional[AccessPolicyTime]) -> Optional[str]:
if value is None:
return None
if isinstance(value, str):
return value
if value.tzinfo is None:
value = value.replace(tzinfo=timezone.utc)
return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")この例の狙いは、SDK内部の仕様を置き換えることではありません。アプリケーション側でログ出力、監査、テスト比較を行う場合に、文字列と日時型の両方を安全に扱うための受け口を作ることです。
サブ秒精度を落とす処理がないか確認する
今回のPRでは、Pythonエミッターで utcDateTime として扱うと精度が失われる点が背景として説明されています。したがって、移行確認では「動くか」だけでなく、サブ秒まで同じ値として保持されるかを見る必要があります。(GitHub)
確認例は次の通りです。
| 確認項目 | 見るべきポイント |
|---|---|
| 単体テスト | 2026-05-05T12:34:56.789Z のような値で、サブ秒が落ちないか |
| スナップショットテスト | 生成されたモデル定義やAPIレビューの差分に string 化が出ていないか |
| ログ・監査 | 日時を丸めた値だけ記録していないか |
| 比較処理 | 文字列比較と日時比較が混在して誤判定しないか |
| シリアライズ | Z やタイムゾーン表記が意図せず変わらないか |
特に、strftime("%Y-%m-%dT%H:%M:%SZ") のように秒までしか出力しない処理を共通化している場合、サブ秒精度を消してしまう可能性があります。AccessPolicy.start / expiry を扱う箇所では、単にUTCへ変換するだけでなく、必要な精度を保持できているか確認しましょう。
SDK再生成やAPIレビューの差分を確認する
Azure REST API Specsを使って社内SDKやラッパーを生成している場合は、PR取り込み後の差分確認が重要です。PR上では、API Change Checkにより TypeSpec、Python、JavaScript のAPIレビューが作成されたことが示されています。(GitHub)
見るべき差分は、次の3つです。
| 差分 | 確認内容 |
|---|---|
| 生成モデルの型 | Python側で AccessPolicy.start / expiry が文字列として扱われるか |
| シリアライズ処理 | 送信前に日時へ変換して精度を落としていないか |
| 既存テスト | datetime 前提のassertが失敗しないか |
CIでSDK生成物のスナップショットを持っている場合、今回のような型表現の変更は差分として検出されやすいはずです。逆に、CIが通っていても日時の精度まで検証していない場合は、専用ケースを追加した方が安心です。
Stored Access PolicyとSAS運用での注意点
今回の変更をきっかけに、SASとStored Access Policyの運用も見直しておくと実務上のトラブルを減らせます。
Azure StorageのSASには、User delegation SAS、Service SAS、Account SASがあります。Microsoftは可能な場合、アカウントキーではなくMicrosoft Entra資格情報で保護されるUser delegation SASを推奨しています。一方で、Stored Access PolicyはService SASで使う仕組みであり、User delegation SASやAccount SASではサポートされません。(Microsoft Learn)
つまり、Stored Access Policyを前提に AccessPolicy.start / expiry を管理している場合は、Service SASの設計として考える必要があります。
start を現在時刻ぴったりにしない
SASの開始時刻を現在時刻に設定すると、クライアントとサービス間の時刻ずれにより、作成直後に一時的な失敗が起こることがあります。Microsoft Learnでは、開始時刻を少なくとも15分前にするか、設定しないことで即時有効にする考え方が示されています。(Microsoft Learn)
実務では、次のように判断するとよいでしょう。
| シーン | 推奨方針 |
|---|---|
| 即時ダウンロードURLを発行する | start を省略する、または少し過去にする |
| 将来時刻から有効にしたい | クライアント側の時刻ではなく、サーバー側でUTC基準に統一する |
| 長時間有効なSASを使う | 期限管理、失効手段、漏えい時の対応をセットで設計する |
| バッチ処理で大量発行する | 開始直後・期限直前の境界値テストを追加する |
SAS URL側とStored Access Policy側で同じ項目を重複指定しない
Stored Access PolicyとSASを組み合わせる場合、必要な認証フィールドは両者で満たす必要があります。ただし、同じフィールドをSAS URL側とStored Access Policy側の両方に指定すると、リクエストが 400 Bad Request になる可能性があります。(Microsoft Learn)
たとえば、ポリシー側に expiry を持たせるなら、SAS生成側で同じ期限を重ねて指定していないか確認してください。これは今回の alternateType 変更とは直接別の話ですが、AccessPolicy.start / expiry を触る改修時に混入しやすいミスです。
失効計画と最小権限を見直す
SASは漏えいすると、取得した第三者が利用できるリスクがあります。Microsoft Learnでは、HTTPSの利用、User delegation SASの優先、失効計画、SAS expiration policy、最小権限などがベストプラクティスとして挙げられています。(Microsoft Learn)
AccessPolicy.expiry の型や表現を見直すだけでは、SAS運用の安全性は上がりません。期限を短くする、権限を読み取りだけにする、IP制限を検討する、監査ログで認可失敗の急増を検知するなど、運用面の対策も合わせて確認しましょう。
Blob、Queue、File、DataLakeの違いをどう見るか
今回のPRでは、FileStorageは既に同じフィールドに対して "javascript, python" を使っており、BlobとQueueをそれに合わせる変更だと説明されています。また、DataLakeは同等のギャップがなく、utcDateTime フィールドが rfc7231 エンコードであるため文字列へのoverrideは不要とされています。(GitHub)
この点は、複数のAzure Storageサービスを横断してSDKを生成・検証しているチームにとって重要です。
| サービス | 今回の見方 |
|---|---|
| Blob Storage | AccessPolicy.start / expiry がPython向けにもstring扱いへ |
| Queue Storage | Blobと同様にPython向けにもstring扱いへ |
| File Storage | 既に同様の指定があったため、今回の整合先 |
| DataLake | 同等のギャップは確認されていないため、今回の変更対象外 |
複数サービスを同じ共通ライブラリで扱っている場合、BlobとQueueだけ特別扱いするのではなく、AccessPolicy 系の日時フィールド全体を「文字列の可能性がある値」として受ける設計にしておくと、将来の生成差分にも強くなります。
実務でのチェックリスト
今回のAzure REST API documentation updateを受けて、対応が必要かどうかは次の順で確認すると効率的です。
| チェック | 対応 |
|---|---|
| PythonでBlobまたはQueueのAccessPolicyを使っているか | 使っていなければ優先度は低い |
| Azure REST API Specsからコード生成しているか | 生成差分と型定義を確認する |
start / expiry を datetime 固定で扱っているか | str も受けられるようにする |
| サブ秒を含む日時を扱うか | 精度保持のテストを追加する |
| SAS URLとStored Access Policyで同じフィールドを重複指定していないか | 400 Bad Request を避けるため見直す |
| 開始時刻を現在時刻ぴったりにしていないか | 省略または余裕を持たせる |
| SASの漏えい・失効時の運用が決まっているか | 期限、権限、監視、失効手順を整備する |
まずは、Pythonコード内で AccessPolicy.start、AccessPolicy.expiry、policy_id、generate_*_sas、set_*_access_policy といったキーワードを検索してください。そのうえで、日時を受け取る箇所、日時を文字列化する箇所、テストで型を比較している箇所を確認するのが最短です。
まとめ：REST APIの仕様変更ではなく、Python生成コードの型表現に注意する
今回の更新は、Azure StorageのREST APIの動作を変えるものではなく、Blob StorageとQueue Storageの AccessPolicy.start / AccessPolicy.expiry について、Python向けクライアント生成でも string を使えるようにするTypeSpec上の調整です。
対応すべき読者は、PythonでAzure StorageのBlobまたはQueueを扱い、特にSASやStored Access Policyの開始時刻・有効期限をコードで管理しているチームです。次に取るべき行動は明確です。AccessPolicy.start / expiry を datetime 固定で扱っていないかを確認し、サブ秒精度を含む文字列を壊さず処理できるようにテストを追加してください。あわせて、SASの開始時刻、期限、最小権限、失効計画も見直すと、今回の更新を単なる型修正ではなく、Storageアクセス制御の品質向上につなげられます。
コメント