Python UUID v4生成ガイド

import uuid

# UUID v4を生成する
request_id = uuid.uuid4()

print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(type(request_id))     # <class 'uuid.UUID'>
print(request_id.version)   # 4

# JSON / HTTPヘッダー用に文字列に変換
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"（ダッシュなし）
print(request_id.bytes)     # b';...'（16生バイト）

import uuid
import requests

def call_api(endpoint: str, payload: dict) -> dict:
    trace_id = str(uuid.uuid4())
    headers = {
        "X-Request-ID": trace_id,
        "Content-Type": "application/json",
    }
    response = requests.post(endpoint, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return {"trace_id": trace_id, "data": response.json()}

# result["trace_id"]で全サービスログから正確なリクエストをgrepできる
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # 例: "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

import uuid

# 1000件のテレメトリイベント用にIDを事前生成
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # 例: "a1c2e3f4-..."
print(event_ids[-1])  # 毎回異なる値

import uuid

u = uuid.uuid4()

print(str(u))         # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"  （36文字）
print(u.hex)          # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"      （32文字、ダッシュなし）
print(u.bytes)        # b';Š...'                       （16バイト、ビッグエンディアン）
print(u.bytes_le)     # b'Š...'                       （16バイト、リトルエンディアン）
print(u.int)          # 78823...（128ビット整数）
print(u.version)      # 4
print(u.variant)      # 'specified in RFC 4122'

# ラウンドトリップ: 文字列から再構築
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True（uがその値だった場合）

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    UUID v4文字列を解析してバリデーションする。
    無効なフォーマットまたは誤ったバージョンの場合はValueErrorを発生させる。
    """
    try:
        u = uuid.UUID(raw)
    except ValueError as exc:
        raise ValueError(f"Invalid UUID format: {raw!r}") from exc

    if u.version != 4:
        raise ValueError(f"Expected UUID v4, got v{u.version}: {raw!r}")

    return u

# FastAPI / Flaskのルートハンドラーでの使用
def get_order(order_id: str):
    try:
        uid = parse_uuid4(order_id)
    except ValueError as exc:
        return {"error": str(exc)}, 400

    # これでDBクエリにuidを安全に使用できる
    return {"order_id": str(uid), "status": "processing"}

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """JSONレスポンスにおいてUUIDとdatetimeオブジェクトをシリアライズする。"""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# ネストされたUUIDを含む実際のAPIレスポンス
api_response = {
    "request_id": uuid.uuid4(),
    "created_at": datetime(2026, 3, 14, 9, 41, 0),
    "order": {
        "id": uuid.uuid4(),
        "customer_id": uuid.uuid4(),
        "items": [
            {"product_id": uuid.uuid4(), "sku": "NVX-9000", "qty": 2},
        ],
    },
}

print(json.dumps(api_response, indent=2, cls=ApiEncoder))
# {
#   "request_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "created_at": "2026-03-14T09:41:00",
#   "order": {
#     "id": "a1c2e3f4-...",
#     ...
#   }
# }

import json, uuid

event_id = uuid.uuid4()
payload = {"event_id": event_id, "action": "checkout"}

# 呼び出し可能オブジェクトを渡す; jsonが処理できない型にのみ呼び出される
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """出荷情報を取得し、型付きUUIDフィールドで返す。"""
    response = requests.get(
        f"https://api.logistics.example.com/v2/shipments/{shipment_id}",
        headers={"Accept": "application/json"},
        timeout=10,
    )
    response.raise_for_status()
    data = response.json()

    # UUIDフィールドをuuid.UUIDオブジェクトに解析し直す
    try:
        data["id"] = uuid.UUID(data["id"])
        data["carrier_id"] = uuid.UUID(data["carrier_id"])
    except (KeyError, ValueError) as exc:
        raise RuntimeError(f"Malformed shipment response: {exc}") from exc

    return data

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """JSONファイルの'correlation_id'を置換または追加する。新しいUUIDを返す。"""
    try:
        with open(path) as f:
            data = json.load(f)
    except FileNotFoundError:
        data = {}
    except json.JSONDecodeError as exc:
        raise ValueError(f"Invalid JSON in {path!r}: {exc}") from exc

    new_id = str(uuid.uuid4())
    data["correlation_id"] = new_id

    with open(path, "w") as f:
        json.dump(data, f, indent=2)

    return new_id

# 単一のUUID v4
python3 -c "import uuid; print(uuid.uuid4())"
# 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e

# ダッシュなし（16進数）形式 — ファイル名や環境変数に便利
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# バッチシードスクリプト用に5つのUUIDを生成
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# シェル変数に使用
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

pip install uuid-utils

# uuid_utilsは標準ライブラリuuidモジュールのドロップイン代替
import uuid_utils as uuid

# 標準ライブラリと同じAPI
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # 標準文字列
print(request_id.hex)       # ダッシュなしの16進数
print(request_id.version)   # 4

# v7（時系列順、DBの主キーに最適）もサポート
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # 現在のタイムスタンププレフィックスで始まる

from dataclasses import dataclass, field
import uuid

@dataclass
class WorkerJob:
    job_id: uuid.UUID = field(default_factory=uuid.uuid4)
    worker_id: str = "worker-01"
    payload: dict = field(default_factory=dict)

job1 = WorkerJob(payload={"task": "resize_image", "src": "uploads/img_4932.png"})
job2 = WorkerJob(payload={"task": "send_email",   "to":  "ops@example.com"})

print(job1.job_id)  # インスタンスごとに一意
print(job2.job_id)  # job1.job_idとは異なる
print(job1.job_id == job2.job_id)  # False

from pydantic import BaseModel, Field
import uuid

class OrderEvent(BaseModel):
    event_id: uuid.UUID = Field(default_factory=uuid.uuid4)
    order_id: uuid.UUID
    status: str
    amount_cents: int

event = OrderEvent(
    order_id=uuid.UUID("a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f"),
    status="payment_confirmed",
    amount_cents=4995,
)

print(event.model_dump_json(indent=2))
# {
#   "event_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "order_id": "a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f",
#   "status": "payment_confirmed",
#   "amount_cents": 4995
# }
# Pydantic v2はuuid.UUIDを自動的に文字列としてシリアライズする