Cisco BMC REST API の概要

はじめに

Representational State Transfer（REST）または RESTful Web サービスを使用すると、インターネット上のコンピューター システム間の相互運用性を提供できます。REST 準拠の Web サービスを使用すると、統一された事前定義された一連のステートレス操作を使用して、Web リソースのテキスト表現にアクセスして操作するようシステムに要求できます。Cisco は、RESTful API を使用して、Redfish™ テクノロジーを使用して UCS C シリーズ サーバーを構成する機能を構築しました。

Redfish™ はオープンな業界標準仕様と構造定義（スキーマ）であり、RESTful インターフェイスと JSON や Odata を活用して顧客が既存のツールとソリューションを統合できるよう支援します。これは、広く使用されているさまざまな拡張性のある IT テクノロジーを利用しており、これらの受け入れられたテクノロジーを使用することにより、Redfish™ の使用を容易にします。Redfish™ は、業界全体で認知されているピアレビュー標準機関である Distributed Management Task Force Inc.（DMTF）の後援および管理を受けています。

DMTF および Redfish™ 標準の詳細については、DMTF および Redfish™を参照してください。

Redfish スキーマと仕様

表 1. Redfish スキーマと仕様

リリース

Redfish スキーマ

Redfish 仕様

リリース 1.0.0.240001

2022.2

v1.9.0

HTTP メソッド（HTTP Methods）

以下で説明するように、次の HTTP メソッドを使用してさまざまなアクションを実装します。

HTTP メソッド

説明

POST

最初の方法は、新しい技術情報を作成するために使用されます。POST 要求は、新しい技術情報が属する技術情報コレクションに送信されます。コレクションを表す技術情報に POST 要求を送信することは、その技術情報のメンバーズ プロパティに同じ要求を送信することと同じです。

最後のメソッドは、オブジェクトに対する操作（アクションなど）を開始するために使用されます。サービスは、アクションを送信するための POST メソッドをサポートする必要があります。POST 操作はべき等ではない場合があります。

GET

GET メソッドは、技術情報の表現を取得するために使用されます。その表現は、単一の技術情報またはコレクションのいずれかです。

PUT

PUT メソッドは、技術情報を完全に置き換えるために使用されます。要求本文から省略されたプロパティは、デフォルト値にリセットされます。

PATCH

PATCH 方式は、既存の技術情報で更新を実行するために使用される推奨方式です。技術情報への変更は、要求本文で送信されます。要求本文で指定されていないプロパティは、PATCH 要求によって直接変更されません。応答は、更新が行われた後の空または技術情報の表現のいずれかです。実装は、独自のポリシーに基づいて特定のフィールドの更新操作を拒否する場合があり、その場合は、要求された更新を適用しません。

DELETE

DELETE メソッドは、 技術情報を取り除くために使用されます。サービスは、削除できる技術情報の DELETE メソッドをサポートする必要があります。

ステータス コード

HTTP は、応答メッセージで返されるステータスコードを定義します。

ステータス コード

ステータス名

説明

200

OK

要求が正常に完了し、本文に表現が含まれています。

201

Created

新しいリソースを作成した要求が正常に完了しました。Location ヘッダーは、新しく作成されたリソースの正規 URI に設定されます。新しく作成されたリソースの表現は、応答本文に含まれる場合があります。

202

Accepted

要求の処理は受け入れられましたが、処理が完了していません。Location ヘッダーは、後で操作のステータスを判断するために照会できるタスクリソースの URI に設定する必要があります。タスク リソースの表現は、応答本文に含めることができます。

204

コンテンツなし

要求は成功しましたが、応答の本文にコンテンツが返されません。

301

完全に移動

要求されたリソースは、別の URI にあります。

302

検出済み

要求されたリソースは一時的に別の URI にあります。

304

未変更

サービスは、アクセスが許可されている条件付き GET 要求を実行しましたが、リソースの内容は変更されていません。条件付き要求は、ヘッダー If-Modified-Since および/または If-None-Match を使用して開始され、変更がない場合はネットワーク帯域幅を節約します。

401

Unauthorized

この要求に含まれる認証クレデンシャルが欠落しているか、無効です。

403

Forbidden

サーバーは要求内のクレデンシャルを認識しましたが、それらのクレデンシャルにはこの要求を実行する権限がありません。

404

Not Found

要求で、存在しないリソースの URI が指定されました。

405

Method Not Allowed

リクエストで指定されたHTTP動詞(DELETE、GET、HEAD、POST、PUT、PATCHなど)は、このリクエストURIではサポートされていません。応答には、Request-URI で識別されるリソースでサポートされるメソッドのリストを提供する Allow ヘッダーが含まれます。

406

Not Acceptable

要求で Accept ヘッダーが指定されましたが、この要求で識別されるリソースは、Accept ヘッダーのメディアタイプの 1 つに対応する表現を生成できません。

409

競合

プラットフォームでサポートされているリソースの現在の状態で競合が発生する可能性があるため（たとえば、互換性のない値を使用してリンクされた方法で機能する複数の属性を設定しようとした場合）、作成要求または更新要求を完了できませんでした。

410

Gone

要求されたリソースがサーバーで使用できず、転送アドレスが不明なことを示しています。この状態は永続的であると見なされます。リンク編集機能を持つクライアントは、ユーザーの承認後に Request-URI への参照を削除する必要があります。サーバーが状態が永続的であるかどうかを認識していない場合、または決定する機能がない場合は、代わりにステータスコード404（Not Found）を使用する必要があります（SHOULD）。この応答は、特に明記されていない限りキャッシュ可能です。

411

必須となる長さ

要求は、Content-Length ヘッダーを使用してコンテンツの長さを指定しませんでした（代わりに Transfer-Encoding：chunked が使用された可能性があります）。アドレス指定されたリソースには、Content-Length ヘッダーが必要です。

412

必須条件に失敗しました

前提条件（OData-Version、If Match、If Not Modified ヘッダーなど）のチェックに失敗しました。

415

Unsupported Media Type

要求で、サポートされていない本文の Content-Type が指定されています。

500

Internal Server Error

サーバーで、要求の処理を妨げる予期しない状態が発生しました。

501

Not Implemented

サーバーは要求を処理するために必要な機能を（現在）サポートしていません。これは、サーバーが要求メソッドを認識せず、リソースのメソッドをサポートできない場合に適切な応答です。

503

Service Unavailable

サーバーの一時的な過負荷またはメンテナンスのため、サーバーは現在リクエストを処理できません。

認証

BMC は、認証を使用して特定の Redfish 技術情報アクセスする必要があります。Redfish は、RFC7617 で定義されている HTTPS 基本認証と呼ばれるアクセス方法を提供し、ユーザーが Redfish 技術情報にアクセスできるようにします。この方法では、TLS に準拠した接続のみを使用して、サードパーティの認証サービスとクライアント間でデータを転送します。ローカル BMC 認証または LDAP や現用系ディレクトリなどのリモート認証を使用してログインします。

curl を使用した HTTPS 基本認証の適用例：

#
#UCS-Server: /logs$ curl -k -X GET https://<username>:<password>@<BMC IP>/redfish/v1 | jq. 
%Total %Received %xferd Average Speed   Time    Time    Time     Current
                        Dload   Upload  Total   Spend    Left    Speed
100 1532 100 1532 0 0   10281       0--:--:--:--:--: :--: :--:   10281{
    "@odata.id": "/redfish/v1",
    "@odata.type": "#ServiceRoot.v1_11_0.ServiceRoot",
    "AccountService": {
        "@odata.id": "/redfish/v1/AccountService"
    },
    "Cables": {
        "@odata.id": "/redfish/v1/Cables"
    },
    "CertificateService": {
        "@odata.id": "/redfish/v1/CertificateService"
    },
    "Chassis": {
        "@odata.id": "/redfish/v1/Chassis"
    },
    "EventService": {
        "@odata.id": "/redfish/v1/EventService"
    },
    "Id": "RootService",
    "JsonSchemas": {
        "@odata.id": "/redfish/v1/JsonSchemas"
    },
    "Links": {
        "Sessions": {
            "@odata.id": "/redfish/v1/SessionService/Sessions"
        }
    },
    "Managers": {
        "@odata.id": "/redfish/v1/Managers"
    },
    "Name": "Root Service",
    "ProtocolFeaturesSupported": {
        "DeepOperations": {
            "DeepPATCH": false,
            "DeepPOST": false
        },
        "ExcerptQuery": false,
        "ExpandQuery": {
            "ExpandAll": false,
            "Levels": false,
            "Links": false,
            "NoLinks": false
        },
        "FilterQuery": false,
        "OnlyMemberQuery": true,
        "SelectQuery": true
    },
    "RedfishVersion": "1.9.0",
    "Registries": {
        "@odata.id": "/redfish/v1/Registries"
    },
    "SessionService": {
        "@odata.id": "/redfish/v1/SessionService"
    },
    "Systems": {
        "@odata.id": "/redfish/v1/Systems"
    },
    "Tasks": {
        "@odata.id": "/redfish/v1/TaskService"
    },
    "TelemetryService": {
        "@odata.id": "/redfish/v1/TelemetryService"
    },
    "UUID": "1b187d13-66a7-4429-8496-b497d28931ba",
    "UpdateService": {
        "@odata.id": "/redfish/v1/UpdateService"
    }
}

利用可能な API

次の Redfish 定義の URI がサポートされています：

Resource

リソース URI

サービス ルート

/redfish/v1/

アカウント サービス

/redfish/v1/AccountService

マネージャ アカウントの収集

/redfish/v1/AccountService/Accounts

マネージャ アカウント

/redfish/v1/AccountService/Accounts/{{account_instance}}

ロール コレクション

/redfish/v1/AccountService/Roles

ロール

/redfish/v1/AccountService/Roles/{{role_instance}}

証明書管理

/redfish/v1/CertificateService

シャーシ収集

/redfish/v1/Chassis

シャーシ

/redfish/v1/Chassis/{{chassis_instance}}

マネージャ収集

/redfish/v1/Managers

マネージャ

/redfish/v1/Managers/{{manager_instance}}

マネージャ ネットワーク プロトコル

/redfish/v1/Managers/{{manager_instance}}/NetworkProtocol

ログ サービスの収集（マネージャ）

/redfish/v1/Managers/{{manager_instance}}/LogServices

ログ サービスの収集（システム）

/redfish/v1/Systems/{{System_Instance}}/LogServices

ログ サービス

/redfish/v1/Managers/{{manager_instance}}/LogServices/

{{manager_log_instance}}

タスクサービス

/redfish/v1/TaskService

タスク収集

/redfish/v1/TaskService/Tasks

タスク

/redfish/v1/TaskService/Tasks/{{Task_Instance}}

ログ エントリ 収集

/redfish/v1/Managers/{{manager_instance}}/LogServices/

{{manager_log_instance}}/Entries

ログ エントリ 収集（システム）

/redfish/v1/Systems/{{System_Instance}}/LogServices/

{{LogService_Instance}}/Entries

redfish/v1/Managers/{{Manager_Instance}}/LogServices/

{{LogService_Instance}}/Entries

ログ エントリ（システム）

/redfish/v1/Managers/{{Manager_Instance}}/LogServices/{{LogService_Instance}}

/Entries/{{Entry_Instance}}

/redfish/v1/Systems/{{System_Instance}}/LogServices/{{LogService_Instance}}

/Entries/{{Entry_Instance}}

ログ エントリ（マネージャ）

/redfish/v1/Managers/{{manager_instance}}/LogServices/{{manager_log_instance}}

/Entries/{{manager_logentry_instance}}

イーサネット インターフェイスの収集

/redfish/v1/Managers/{{manager_instance}}/EthernetInterfaces

イーサネット インターフェイス

/redfish/v1/Managers/{{manager_instance}}/EthernetInterfaces/{{manager_ethifc_instance}}

イベント サービス

/redfish/v1/EventService

セッション サービス

/redfish/v1/SessionService

セッション収集

/redfish/v1/SessionService/Sessions

セッション

/redfish/v1/SessionService/Sessions/{{session_id}}

サービスの更新

/redfish/v1/UpdateService

FirmwareInventory 収集

/redfish/v1/UpdateService/FirmwareInventory

FirmwareInventory

/redfish/v1/UpdateService/FirmwareInventory/{{firmwareinventory_instance}}

レジストリ

/redfish/v1/Registries

システム（System）

/redfish/v1/Systems

OData プロパティ

OData プロパティは、URI によってアクセスされる ID、タイプ、コンテキストなどのリソースに関する情報を提供するために使用されます。REST API で使用されるプロパティは次のとおりです：

表 2. OData 属性

名前

タイプ

読み取り専用

説明

@odata.id

文字列

はい（True）

このプロパティは、リソースの一意の識別子です。これは Redfish 仕様で定義されているフォーマットに従います。

@odata.type

文字列

はい（True）

このプロパティは、リソース タイプを指定する絶対 URL です。これは Redfish 仕様で定義されているフォーマットに従います。各 Redfish エンティティの型の値は、[スキーマ（Schema）] 列の下の Redfish API にリストされているように、従うスキーマを示します。

例

{
"@odata.id": "/redfish/v1/",
"@odata.type": "#ServiceRoot.v1_11_0.ServiceRoot"
}

Resource

このトピックで指定されているリソースのプロパティは、このドキュメントで言及されているすべての API に継承されます。次に、さまざまなリソース スキーマのプロパティを示します。

表 3. リソース タイプの定義

名前

タイプ

読み取り専用

説明

ID

文字列

はい（True）

このプロパティは、類似するリソースの中でリソースを一意に識別します。

説明

Null、文字列

はい（True）

このプロパティにより、リソースの説明が提供され、スキーマ定義の一貫性が確保されます。

Name

String

はい（True）

このプロパティは、リソースの名前を示します。

UUID

文字列

はい（True）

このプロパティは次のパターンに従います。([0-9a-

f]{8}-[0-9a-f]{4}-[0-9a-

f]{4}-[0-9a-f]{4}-[0-9a-

f]{12})。
表 4. ロケーションの定義

名前

タイプ

読み取り専用

説明

PartLocation

オブジェクト

はい（True）

このプロパティは、部品がエンクロージャ内のどこにあるかを示します。

ServiceLabel

文字列

はい（True）

このプロパティは、シルク スクリーン名や印刷ラベルなど、部品の場所のラベルです。

LocationOrdinalValue

物理ポートの

はい（True）

このプロパティは、部品の数値的な位置を表します。たとえば、LocationType が Slot で、ユニットがスロット 2 にある場合、この値は 2 です。

LocationType

文字列

はい（True）

このプロパティは、部品の場所のタイプを指定します。

  • Backplane：バックプレーン。

  • Bay：ベイ

  • Connector：コネクタまたはポート。

  • Embedded：部品内に埋め込まれます。

  • Slo：スロット。

  • Socket：ソケット。

表 5. ステータスの定義

名前

タイプ

読み取り専用

説明

正常性

文字列

はい（True）

このプロパティは、依存リソースなしでのリソースの正常性ステータスを表示します。

列挙型オプション：

  • OK：正常。

  • 警告：注意が必要な状態です。

  • クリティカル：クリティカルな状態、ただちに注意が必要です。

HealthRollup

文字列

はい（True）

このプロパティは、このリソースの観点からの全体的な正常性ステータスを示します。

列挙型オプション：

  • OK：正常。

  • 警告：注意が必要な状態です。

  • クリティカル：クリティカルな状態、ただちに注意が必要です。

ステータス

文字列

はい（True）

リソースを有効にするか無効にするかを指定します。

列挙型オプション：

  • Enabled：この機能またはリソースは有効です。

  • Disabled：この機能またはリソースは無効です。

サービス ルート

このリソースは、「/redfish/v1/」URI にある Redfish サービスのルートを表します。ハイパーメディア API として、このデバイスの Redfish インターフェイスを介してアクセスできる他のすべてのリソースは、サービス ルートから直接的または間接的にリンクされます。

GET

https://<username>:<password>@<BMC IP>/redfish/v1
Content-Type:application/json

応答

要求への応答は JSON フォーマットになります。プロパティを次の表に示します。

表 6. サービス ルート プロパティ

名前

タイプ

受信可のみ

説明
@odata.id 文字列 はい（True）

「OData プロパティ」を参照してください。

@odata.type 文字列 はい（True）

「OData プロパティ」を参照してください。

AccountService オブジェクト はい（True） アカウント サービスへのリンク。
CertificateService オブジェクト はい（True） 証明書サービスへのリンク。
シャーシ オブジェクト はい（True） シャーシのコレクションへのリンク。
ComponentIntegrity オブジェクト はい（True） 重要で関連性の高いセキュリティ情報を提供します。
EventService オブジェクト はい（True） イベント サービスへのリンク。
Id 文字列 はい（True）

詳細については、Resource を参照してください。

JsonSchemas オブジェクト はい（True） JSON スキーマ ファイルのコレクションへのリンク。

Links

オブジェクト

はい（True）

関連リソースへのリンクを含みます：

  • Sessions：セッションのコレクションへのリンクを提供します。

  • ManagerProvidingService：マネージャのコレクションへのリンクを提供します。

マネージャ

オブジェクト

はい（True）

 マネージャのコレクションへのリンクを提供します

Name

String

はい（True）

詳細については、Resource を参照してください。

製品

文字列

はい（True）

このサーバーの製品名。

ProtocolFeaturesSupported

オブジェクト

はい（True）

サポートされているプロトコル機能の詳細：

  • DeepOperations：プロパティについては 表 2 を参照してください。

  • ExcerptQuery：「excerpt」クエリ パラメータがサポートされているかどうかを示します。

  • ExpandQuery：サービスでの $expand の使用に関する詳細が含まれます。プロパティについては 表 3 を参照してください。

  • FilterQuery：$filter クエリパラメータがサポートされているかどうかを示します。

  • OnlyMemberQuery：「only」クエリパラメータがサポートされているかどうかを示します。

  • SelectQuery：$select クエリーパラメータがサポートされているかどうかを示します。

RedfishVersion

文字列

はい（True）

この文字列は Redfish サービスのバージョンを表します。

Registries

オブジェクト

はい（True）

レジストリのコレクションへのリンク。

SessionService

オブジェクト

はい（True）

セッションサービスへのリンクを提供します。

システム（Systems）

オブジェクト

はい（True）

システムのコレクションへのリンクを提供します。

タスク

オブジェクト

はい（True）

タスク サービスへのリンクを提供します。

TelemetryService

オブジェクト

はい（True）

テレメトリサービスへのリンクを提供します。

UUID

文字列

はい（True）

詳細については、Resource を参照してください。

UpdateService

オブジェクト

はい（True）

更新サービスへのリンクを提供します。

ベンダー

文字列

はい（True）

このサーバーのベンダーの名前。
表 7. DeepOperations プロパティ

名前

タイプ

読み取り専用

説明

DeepPATCH

ブール

True

サービスがディープ PATCH 操作をサポートしているかどうかを示します。

DeepPOST

ブール

True

サービスがディープ POST 操作をサポートしているかどうかを示します。
表 8. ExpandQuery プロパティ

名前

タイプ

読み取り専用

説明

すべて展開

ブール

True

サービスが $expand アステリスク（*）を使用したすべてのエントリの展開をサポートしているかどうかを示します。

レベル

ブール

True

サービスが拡張の $levels 修飾子をサポートしているかどうかを示します。

Links

ブール

True

サービスが $expand チルダ（~）を使用したリンク セクションのエントリのみの展開をサポートしているかどうかを示します。

NoLinks

ブール

True

サービスが $expand ピリオド（.）を使用したリンク セクションにはないエントリの拡張のみをサポートするかどうかを示します。

[コレクション（Collection）]

表 9. コレクションのプロパティ

名前

タイプ

読み取り専用

説明

@odata.id

文字列

はい（True）

詳細については、OData プロパティ を参照してください。

@odata.type

文字列

はい（True）

詳細については、OData プロパティ を参照してください。

メンバー

配列

はい（True）

このコレクションのメンバーを含みます。

Members@odata.count

物理ポートの

はい（True）

コレクション内のメンバー数を示します。

Name

String

はい（True）

コレクションの名前を指定します。

説明

文字列

はい（True）

リソースに関する詳細を提供します。