メインコンテンツへスキップ

Unraid API の使用

Unraid API は、Unraid サーバーとやり取りできる GraphQL インターフェースを提供します。このガイドでは、認証、一般的なクエリ、使用パターンを扱います。

GraphQL サンドボックスを有効にする​

WebGUI の方法（推奨）​

📖 ライブドキュメント

完全な API スキーマとドキュメントを表示:

Apollo GraphQL Studio でライブドキュメントを表示 →

Web GUI を使用するのが、GraphQL サンドボックスを有効にする最も簡単な方法です。

WebGUI の方法（推奨）​

WebGUI を使うのが、GraphQL サンドボックスを有効にする最も簡単な方法です:

  1. 設定 → 管理アクセス → 開発者オプション に移動する

  2. GraphQL Sandbox のトグルを有効にする

  3. 次の場所に移動して、GraphQL プレイグラウンドにアクセスします:

    http://YOUR_SERVER_IP/graphql

CLI の方法​

あるいは、CLI を使用して開発者モードを有効にできます:

unraid-api developer --sandbox true

または、対話モードを使用します:

unraid-api developer

認証​

ほとんどのクエリとミューテーションには認証が必要です。リクエストには必ず適切な資格情報を含めてください。

  1. API キー - プログラムからのアクセス用
  2. Cookie - WebGUI にサインインすると自動的に使用されます
  3. SSO/OIDC - 外部プロバイダーで構成されている場合

API キーの管理​

Unraid WebGUI の設定 → 管理アクセス → APIキーに移動します。

  • 既存の API キーを表示する
  • 新しい API キーを作成する
  • 権限とロールを管理する
  • キーを取り消すか再生成する

API キーの管理​

生成された API キーは、GraphQL リクエストのヘッダーとして含める必要があります。

{
    "x-api-key": "YOUR_API_KEY"
}

利用可能なスキーマ​

API は、Unraid サーバーのさまざまな側面にアクセスできます:

  • システム情報: CPU、メモリ、OS 情報を含むシステムの詳細を照会します。システムの状態と健全性を監視し、ベースボードとハードウェア情報にアクセスします。
  • Array 管理: array の状態と構成を照会します。array の操作（開始/停止）を管理し、ディスクの状態と健全性を監視し、parity checks を実行します。array の操作の詳細については、Array の概要 を参照してください。
  • Docker 管理: Docker コンテナを一覧表示および管理します。コンテナの状態を監視し、Docker ネットワークを管理します。
  • リモートアクセス: リモートアクセス設定を構成および管理します。SSO 構成を扱い、許可されたオリジンを管理します。

システム情報​

システム情報​

query {
    info {
        os {
            platform
            distro
            release
            uptime
        }
        cpu {
            manufacturer
            brand
            cores
            threads
        }
    }
}

アレイ管理​

query {
    array {
        state
        capacity {
            disks {
                free
                used
                total
            }
        }
        disks {
            name
            size
            status
            temp
        }
    }
}

Docker 管理​

query {
    dockerContainers {
        id
        names
        state
        status
        autoStart
    }
}

リモートアクセス​

API にはいくつかのコア型が含まれます。ベース型には、Node（一意の ID を持つオブジェクト向けのインターフェース。詳しくは Object Identification を参照）、JSON（複雑な JSON データ用）、DateTime（タイムスタンプ値用）、Long（64 ビット整数用）があります。リソース型には、Array（array およびディスク管理）、Docker（コンテナおよびネットワーク管理）、Info（システム情報）、Config（サーバー設定）、Connect（リモートアクセス設定）があります。利用可能なロールは admin（フルアクセス）、connect（リモートアクセス機能）、guest（制限付き読み取りアクセス）です。

💻 クエリ例​

Pro ヒント
  1. Apollo GraphQL Studio を使用して、完全な API スキーマとドキュメントを表示および確認する
  2. 小さなクエリから始め、必要に応じてフィールドを徐々に追加します
  3. パフォーマンスを維持するために、クエリの複雑さを監視します
  4. API キーには適切なロールと権限を使用します
  5. API キーは安全に保管し、定期的にローテーションします

Docker コンテナを一覧表示する​

Rate 制限

API は、不正使用を防ぐためにレート制限を実装しています。アプリケーションがレート制限レスポンスを適切に処理するようにしてください。

API は、次の形式で標準の GraphQL エラーを返します:

{
  "errors": [
    {
      "message": "Error description",
      "locations": [...],
      "path": [...]
    }
  ]
}

リソース型​

Learn さらに
  • Apollo GraphQL Studio を使用して、完全な API スキーマとドキュメントを表示する
  • Apollo Sandbox のスキーマエクスプローラーを使用して、利用可能なすべての型とフィールドを参照します
  • 詳細なフィールド説明については、Apollo Sandbox のドキュメントタブを確認してください
  • unraid-api status を使用して API の健全性を監視します
  • トラブルシューティングには unraid-api report を使用してレポートを生成します

特定のコマンドや構成オプションの詳細については、CLI ドキュメント を参照するか、unraid-api --help を実行してください。問題が発生した場合は、コミュニティサポートのために Unraid forums をご覧ください。