プログラムによるAPIキー管理

このガイドでは、Unraid API CLIを使用してAPIキーをプログラムで作成、使用、削除する方法を説明し、自動化ワークフローやスクリプトを可能にします。

概要

unraid-api apikey コマンドは対話モードと非対話モードの両方をサポートしており、次の用途に適しています:

APIキーの作成

Complete Workflow Example にジャンプして、すべてが実際に動作する様子を確認してください。

機械可読な出力を取得するには、--json フラグを使用します:

unraid-api apikey --create --name "workflow key" --roles ADMIN --json

出力:

{
    "key": "your-generated-api-key-here",
    "name": "workflow key",
    "id": "generated-uuid"
}

機械可読な出力を取得するには、--json フラグを使用します:

unraid-api apikey --create \
  --name "limited access key" \
  --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
  --description "Read-only access for monitoring" \
  --json

出力:

同じ名前のキーが存在する場合は、--overwrite を使用します:

unraid-api apikey --create --name "existing key" --roles ADMIN --overwrite --json

警告

--overwrite フラグは、既存のキーを永続的に置き換えます。古いキーは直ちに無効になります。

APIキーの削除

--overwrite フラグは、既存のキーを永続的に置き換えます。古いキーは直ちに無効になります。

プロンプトなしで名前によってキーを削除します:

unraid-api apikey --delete --name "workflow key"

出力:

Successfully deleted 1 API key

プロンプトなしで名前によってキーを削除します:

機械可読な削除確認には --json フラグを使用します:

unraid-api apikey --delete --name "workflow key" --json

成功時の出力:

{
    "deleted": 1,
    "keys": [
        {
            "id": "generated-uuid",
            "name": "workflow key"
        }
    ]
}

エラー出力:

{
    "deleted": 0,
    "error": "No API key found with name: nonexistent key"
}

成功時の出力:

指定されたキーが存在しない場合:

unraid-api apikey --delete --name "nonexistent key"
# Output: No API keys found to delete

JSONエラー出力:

{
    "deleted": 0,
    "message": "No API keys found to delete"
}

完全なワークフローの例

JSONエラー出力:

#!/bin/bash
set -e

# 1. Create temporary API key
echo "Creating temporary API key..."
KEY_DATA=$(unraid-api apikey --create \
  --name "temp deployment key" \
  --roles ADMIN \
  --description "Temporary key for deployment $(date)" \
  --json)

# 2. Extract the API key
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "API key created successfully"

# 3. Use the key for operations
echo "Configuring services..."
curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "azure", "clientId": "your-client-id"}' \
  http://localhost:3001/graphql

# 4. Clean up (always runs, even on error)
trap 'echo "Cleaning up..."; unraid-api apikey --delete --name "temp deployment key"' EXIT

echo "Deployment completed successfully"

完全なワークフローの例

一時アクセスのプロビジョニングの完全な例を示します:

旗	説明	例
--name <name>	キー名（必須）	--name "my key"
--roles <roles>	カンマ区切りのロール	--roles ADMIN,VIEWER
--permissions <perms>	Resource:action の組み合わせ	--permissions "DOCKER:READ_ANY"
--description <desc>	キーの説明	--description "CI/CD key"
--overwrite	既存のキーを置き換える	--overwrite
--json	機械可読な出力	--json

利用可能なロール: ADMIN（システム全体へのアクセス）、CONNECT（Unraid Connect の機能）、VIEWER（読み取り専用アクセス）、GUEST（制限付きアクセス）。

利用可能なリソース: ACTIVATION_CODE, API_KEY, ARRAY, CLOUD, CONFIG, CONNECT, CONNECT__REMOTE_ACCESS, CUSTOMIZATIONS, DASHBOARD, DISK, DISPLAY, DOCKER, FLASH, INFO, LOGS, ME, NETWORK, NOTIFICATIONS, ONLINE, OS, OWNER, PERMISSION, REGISTRATION, SERVERS, SERVICES, SHARE, VARS, VMS, WELCOME.

利用可能なアクション: CREATE_ANY, CREATE_OWN, READ_ANY, READ_OWN, UPDATE_ANY, UPDATE_OWN, DELETE_ANY, DELETE_OWN.

削除コマンドのオプション:

旗	説明	例
--delete	削除モードを有効にする	--delete
--name <name>	削除するキー（任意）	--name "my key"

--name を省略すると、コマンドは対話的に実行されます。

リソース: ACTIVATION_CODE, API_KEY, ARRAY, CLOUD, CONFIG, CONNECT, CONNECT__REMOTE_ACCESS, CUSTOMIZATIONS, DASHBOARD, DISK, DISPLAY, DOCKER, FLASH, INFO, LOGS, ME, NETWORK, NOTIFICATIONS, ONLINE, OS, OWNER, PERMISSION, REGISTRATION, SERVERS, SERVICES, SHARE, VARS, VMS, WELCOME

リソース: ACTIVATION_CODE, API_KEY, ARRAY, CLOUD, CONFIG, CONNECT, CONNECT__REMOTE_ACCESS, CUSTOMIZATIONS, DASHBOARD, DISK, DISPLAY, DOCKER, FLASH, INFO, LOGS, ME, NETWORK, NOTIFICATIONS, ONLINE, OS, OWNER, PERMISSION, REGISTRATION, SERVERS, SERVICES, SHARE, VARS, VMS, WELCOME

トラブルシューティング

一般的なエラーメッセージ:

• "API key name must contain only letters, numbers, and spaces": ハイフン、アンダースコア、記号などの特殊文字を削除してください。
• "API key with name 'x' already exists": --overwrite フラグを使用するか、別の名前を選択してください。
• "Please add at least one role or permission to the key": --roles または --permissions のいずれか（または両方）を指定してください。

トラブルシューティングのため、デバッグログを有効にして実行してください:

LOG_LEVEL=debug unraid-api apikey --create --name "debug key" --roles ADMIN