cURL で Microsoft Azure にファイルを効率的にエクスポート
cURL で Azure Blob Storage にファイルをエクスポートするには、x-ms-blob-type: BlockBlob を指定した認証付きの PUT を送信します。以下の例では、既存のストレージアカウントキーでリクエストに署名し、既存の Blob の置き換えを拒否します。さらに結果をダウンロードして、ローカルファイルとバイト単位で比較します。
前提条件の確認
Node.js と cURL がインストールされた Linux シェルを使用します。この例は Node.js 26.12.0 と cURL 8.23.0 でテスト済みです。同じ条件で再現するには、これらのバージョンを使用してください。Node は、コンパイラーやパッケージのインストールなしで TypeScript ヘルパーを実行します。ツールは Node.js のダウンロードページと cURL のリリースから入手できます。
プログラムを保存する前に、両方の実行ファイルを確認してください。
node --version && curl --version
次のものも必要です。
- 公開 Azure エンドポイント
https://ACCOUNT.blob.core.windows.net経由でアクセスできる、既存のストレージアカウントと非公開コンテナー。新規プロジェクトでは、サポート対象の汎用 v2 アカウントを使用してください。アカウントとコンテナーのプロビジョニングは、この手順の対象外です。 - そのアカウントで Shared Key を使用する権限と、組織のシークレット管理手順で提供される Base64 形式のアカウントキー。自分だけが読み取れる保護されたファイルに保存してください。プログラムは標準入力からそのファイルを読み取ります。プロジェクトおよびバージョン管理の対象外に置いてください。
- サイズがゼロから 8 MiB までの通常のローカルファイル。検証が完了するまで変更しないでください。この小容量ファイル向けの例は、入力とダウンロードしたバイト列をメモリに保持します。
ローカルパス全体には、印字可能な ASCII 文字を使用してください。リモートの Blob 名はスラッシュで区切ったセグメントで構成し、各セグメントには英字、数字、ピリオド、アンダースコア、ハイフンを使用します。各セグメントの先頭は英字、数字、アンダースコア、ハイフンのいずれかにしてください。このヘルパーは URL エンコードを推測せず、それ以外の名前を意図的に拒否します。空のファイルも有効です。
リクエストへの署名
Shared Key は、HTTP メソッド、所定のリクエストヘッダー、リソースパスを対象にした
HMAC-SHA256 署名を使用します。アカウントキーは、署名前に Base64 デコードします。ヘッダーの順序は重要です。また、ゼロバイトのアップロードでは、HTTP の Content-Length が 0 でも、署名内の content-length フィールドは空にします。これらの詳細は Microsoft の Shared Key 仕様に従っています。
アカウントキーは広範なアクセスを許可します。Microsoft は、可能な場合にはマネージド ID と Microsoft Entra ID の使用を推奨しています。この処理設定は、Shared Key の使用がすでに許可されている環境専用です。このプログラムでは、アカウントキーの代わりに Bearer トークンや SAS トークンは使用できません。
このプログラム全体を azure-upload.mts として保存してください。.mts 拡張子により、既存の CommonJS プロジェクト内でもモジュール形式が明示されます。
import { spawnSync } from 'node:child_process'
import { createHash, createHmac } from 'node:crypto'
import { readFileSync, statSync } from 'node:fs'
import { resolve } from 'node:path'
const maxBytes = 8 * 1024 * 1024
function main(): void {
const [input, account, container, blob, ...extra] = process.argv.slice(2)
if (!input || !account || !container || !blob || extra.length > 0) {
throw new Error('Usage: node azure-upload.mts FILE ACCOUNT CONTAINER BLOB < KEY_FILE')
}
const file = resolve(input)
if (!/^[\x20-\x7e]+$/.test(file)) throw new Error('Use a printable ASCII local path.')
if (!/^[a-z0-9]{3,24}$/.test(account)) throw new Error('Invalid account name.')
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(container) || container.length < 3 || container.length > 63) {
throw new Error('Invalid container name.')
}
if (blob.length > 1024 || !blob.split('/').every((part) => /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(part))) {
throw new Error('Use simple slash-separated blob-name segments.')
}
const info = statSync(file)
if (!info.isFile() || info.size > maxBytes) throw new Error('Use a regular file of at most 8 MiB.')
const original = readFileSync(file)
if (original.length > maxBytes) throw new Error('The input grew beyond 8 MiB.')
const encodedKey = readFileSync(0, 'utf8').trim()
if (!/^[A-Za-z0-9+/]{86}==$/.test(encodedKey)) throw new Error('Expected a Base64 512-bit account key.')
const key = Buffer.from(encodedKey, 'base64')
const url = `https://${account}.blob.core.windows.net/${container}/${blob}`
function request(method: 'PUT' | 'GET'): Buffer {
const uploading = method === 'PUT'
const length = uploading ? original.length : 0
const contentType = uploading ? 'application/octet-stream' : ''
const azureHeaders = [
...(uploading ? ['x-ms-blob-type:BlockBlob'] : []),
`x-ms-date:${new Date().toUTCString()}`,
'x-ms-version:2023-11-03',
]
const fields = [method, '', '', length === 0 ? '' : String(length), '', contentType,
'', '', '', uploading ? '*' : '', '', '']
const stringToSign = `${fields.join('\n')}\n${azureHeaders.join('\n')}\n/${account}/${container}/${blob}`
const signature = createHmac('sha256', key).update(stringToSign).digest('base64')
const headers = [
...azureHeaders,
`Authorization: SharedKey ${account}:${signature}`,
...(uploading ? [`Content-Length: ${length}`, `Content-Type: ${contentType}`, 'If-None-Match: *'] : []),
]
const result = spawnSync('curl', [
'--disable', '--globoff', '--silent', '--show-error', '--fail', '--proto', '=https',
'--request', method, '--header', '@-',
'--write-out', '%{stderr}HTTP:%{http_code}',
...(uploading ? ['--upload-file', file] : []),
'--output', uploading ? '/dev/null' : '-', url,
], { input: `${headers.join('\n')}\n`, maxBuffer: maxBytes + 65536 })
const status = /HTTP:(\d{3})$/.exec(result.stderr?.toString() ?? '')?.[1] ?? 'unknown'
if (result.status !== 0 || status !== (uploading ? '201' : '200')) {
console.error(`${method} failed: HTTP ${status}; cURL exit ${result.status ?? 'unknown'}.`)
throw new Error('Request failed.')
}
return result.stdout
}
request('PUT')
const downloaded = request('GET')
if (!original.equals(downloaded)) throw new Error('Downloaded bytes differ from the input.')
const sha256 = createHash('sha256').update(original).digest('hex')
console.log(`Verified ${original.length} bytes; SHA-256 ${sha256}`)
}
try {
main()
} catch {
console.error('Export failed. Check the input, account key, destination, and connection.')
process.exitCode = 1
}
ヘルパーは --header @- を使い、標準入力経由で認証ヘッダーを cURL に渡すため、キーや署名はコマンド引数に含まれません。また、保存済みの cURL 設定によって再試行が追加されたり、出力処理が変更されたりしないよう、.curlrc の読み込みも無効にします。認証情報を扱う際は、シェルのトレースや cURL の trace/verbose オプションを使用しないでください。これらのオプションについては、cURL マニュアルを参照してください。
アップロードとバイト列の確認
以下のアカウント、コンテナー、保存先の Blob 名、キーファイルのパスを置き換えてください。コンテナーは既存のものが必要です。保存先には、まだ存在しない名前を選んでください。azure-upload.mts と入力ファイルがあるディレクトリで、次のコマンドを実行します。
node azure-upload.mts ./localfile.bin youraccount yourcontainer exports/localfile.bin < /secure/path/azure-account.key
Put Blob が成功すると、HTTP 201 が返ります。続いてプログラムは、別の認証付きダウンロードで HTTP 200 を要求し、レスポンス全体と元の入力を比較します。両方の確認に合格した後にのみ、Verified、バイト数、SHA-256 ダイジェストを出力します。アップロードが成功しただけでは、このメッセージは出力されません。Blob は非公開コンテナーに残り、このプログラムでは削除しません。
拒否や結果が不確かな場合の対処
If-None-Match: * 条件により、アップロードは新規作成のみに限定されます。既存の保存先に対してコマンドを再実行すると、必ず失敗し、そのバイト列は変更されません。Azure は 409 と BlobAlreadyExists、または 412 の条件エラーを返す場合があります。すべての競合を認証の問題と判断しないでください。Microsoft は
Blob Storage のエラーコードを公開しています。プログラムは HTTP ステータスと cURL 終了コードだけを報告し、プロバイダーのエラー本文は出力しません。
403 の場合はアクセスの確認が必要です。アカウントとキーの組み合わせ、Shared Key の使用許可、利用中のネットワークからそのアカウントにアクセスできるかを確認してください。HTTP ステータスが報告される前にプログラムが失敗した場合は、ローカルファイルとキーファイルのパスを確認してください。自動再試行は有効になっていません。
接続が切れると、書き込み結果が不確かになる場合があります。レスポンスが失われる前に、Azure が Blob を保存している可能性があるためです。検証用のダウンロードに失敗した場合も、アップロード済みの Blob は残ります。通常使用している認証付きのストレージツールで、その保存先自体を調べ、ダウンロードしたバイト列を比較してから、残すか削除するかを判断してください。この新規作成専用コマンドを再実行しても、既存の Blob の内容は確認できず、置き換えも行いません。再試行を成功させるためだけに、既存の保存先を削除しないでください。
大容量転送向けの別ツールの選択
8 MiB という上限は、メモリにバッファリングするこの例の制限であり、Azure サービスの制限ではありません。ブロックをステージングしてコミットする代わりに、単一の Put Blob リクエストを使用します。大容量ファイル、転送の再開、バッチ自動化が必要な場合は、それらの転送を管理するストレージクライアントを使用してください。この例では、複数ブロックの処理やスループットを保証しません。小規模な REST エクスポートでは対応できなくなった場合は、Azure Blob クライアントライブラリが次の選択肢として役立ちます。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
