SANtricity 11.8 Solutions

to English version

APIの基本

Web Services APIのHTTP通信は、要求と応答のサイクルで構成されます。

要求のURL要素

使用するプログラミング言語やツールに関係なく、Web Services APIの各呼び出しは、URL、HTTP動詞、およびAcceptヘッダーを含む同様の構造を持ちます。

すべての要求には次のようなURLが含まれ、以下の表に示す要素で構成されます。

https://webservices.name.com:8443/devmgr/v2/storage-systems

領域説明

領域	説明
HTTP転送プロトコル `https://`	Web Services ProxyではHTTPまたはHTTPSを使用できます。組み込み版のWeb Servicesにはセキュリティ上の理由からHTTPSが必要です。
ベースURLとポート `webservices.name.com:8443`	各要求がWeb Servicesのアクティブなインスタンスに正しくルーティングされるように、インスタンスの完全修飾ドメイン名（FQDN）またはIPアドレス、およびリスニングポートが必要です。デフォルトでは、Web Servicesの通信にはポート8080（HTTP）とポート8443（HTTPS）が使用されます。 Web Services Proxyでは、どちらのポートもインストール時またはwsconfig.xmlファイルで変更可能です。さまざまな管理アプリケーションを実行するデータセンターホストでは、ポートの競合は珍しくありません。組み込みのWeb Servicesでは、コントローラー上のポートは変更できず、デフォルトのポート8443を使用してセキュアーな接続が確立されます。
APIパス `devmgr/v2/storage-systems`	要求はWeb Services API内の特定のRESTリソース（エンドポイント）に対して実行されます。ほとんどのエンドポイントは次の形式です。 `devmgr/v2/<resource>/[id]` APIパスは次の3つの部分で構成されます。 `devmgr`（Device Manager）は、Web Services APIのネームスペースです。 `v2` は、アクセスするAPIのバージョンです。`utils` を使用してログインエンドポイントにアクセスすることもできます。 `storage-systems` は、ドキュメント内のカテゴリーです。

HTTP転送プロトコル

https://

Web Services ProxyではHTTPまたはHTTPSを使用できます。

組み込み版のWeb Servicesにはセキュリティ上の理由からHTTPSが必要です。

ベースURLとポート

webservices.name.com:8443

各要求がWeb Servicesのアクティブなインスタンスに正しくルーティングされるように、インスタンスの完全修飾ドメイン名（FQDN）またはIPアドレス、およびリスニングポートが必要です。デフォルトでは、Web Servicesの通信にはポート8080（HTTP）とポート8443（HTTPS）が使用されます。

Web Services Proxyでは、どちらのポートもインストール時またはwsconfig.xmlファイルで変更可能です。さまざまな管理アプリケーションを実行するデータセンターホストでは、ポートの競合は珍しくありません。

組み込みのWeb Servicesでは、コントローラー上のポートは変更できず、デフォルトのポート8443を使用してセキュアーな接続が確立されます。

APIパス

devmgr/v2/storage-systems

要求はWeb Services API内の特定のRESTリソース（エンドポイント）に対して実行されます。ほとんどのエンドポイントは次の形式です。

devmgr/v2/<resource>/[id]

APIパスは次の3つの部分で構成されます。

devmgr（Device Manager）は、Web Services APIのネームスペースです。
v2 は、アクセスするAPIのバージョンです。utils を使用してログインエンドポイントにアクセスすることもできます。
storage-systems は、ドキュメント内のカテゴリーです。

サポートされるHTTP動詞

サポートされるHTTP動詞には、GET、POST、およびDELETEがあります。

GET要求は読み取り専用要求に使用されます。
POST要求はオブジェクトの作成と更新に使用されます。また、セキュリティに影響する可能性のある読み取り要求にも使用されます。
DELETE要求は、一般にオブジェクトを管理対象から削除したり、オブジェクトを完全に削除したり、オブジェクトの状態をリセットしたりするために使用されます。

現在のところ、Web Services APIではPUTおよびPATCHはサポートしていません。代わりに、POSTを使用してこれらの動詞の代表的な機能を実行できます。

Acceptヘッダー

特に指定がないかぎり、Web Servicesは要求の本文をJSON形式で返します。一部のクライアントは、デフォルトで「text/html」などを要求します。この場合、APIは要求された形式でデータを提供できないことを示すHTTPコード406で応答します。ベストプラクティスとして、応答にJSON形式が必要なケースのためにAcceptヘッダーを「application/json」と定義することを推奨します。応答本文が返されないそれ以外のケース（DELETEなど）では、Acceptヘッダーを指定しても意図しない結果が生じることはありません。

応答

APIに要求を送信すると、次の2つの重要な情報が応答として返されます。

HTTPステータスコード：要求が成功したかどうかを示します。
応答本文（オプション）：通常は、リソースの状態を示すJSON本文、または失敗の詳しい状況を示す本文が返されます。

ステータスコードとcontent-typeヘッダーから、応答本文の内容を判断する必要があります。HTTPステータスコードが200～203および422の場合、Web Servicesは応答でJSON本文を返します。それ以外のHTTPステータスコードの場合、Web Servicesは一般にJSON本文を返しません。これは、仕様で許可されていない（204）か、ステータスが説明を必要としないためです。次の表に、一般的なHTTPステータスコードとその定義を示します。また、各HTTPコードに関連付けられた情報がJSON本文で返されるかどうかも示します。

HTTPステータスコード	説明	JSON本文
200 OK	処理に成功したことを示します。	○
201 Created	オブジェクトが作成されたことを示します。このコードは、ステータス200の代わりにごくまれに使用されます。	○
202 Accepted	要求は非同期要求としての処理を承認されましたが、実際の結果を取得するためには再度要求が必要です。	○
203 Non-Authoritative Information	200と同様ですが、Web Servicesはデータが最新であることを保証できません（その時点でキャッシュデータしか使用できない場合など）。	○
204 No Content	処理には成功しましたが、応答本文はありません。	×
400 Bad Request	要求のJSON本文が有効でないことを示します。	×
401 Unauthorized	認証に失敗したことを示します。クレデンシャルが指定されていないか、ユーザー名またはパスワードが無効です。	×
403 Forbidden	認証に失敗したことを示します。認証されたユーザーに要求したエンドポイントにアクセスする権限がありません。	×
404 Not Found	要求されたリソースが見つからなかったことを示します。このコードは、識別子で要求されたAPIやリソースが存在しない場合に使用されます。	×
422 Unprocessable Entity	要求の形式には問題はありませんが、入力パラメーターが無効であるか、ストレージシステムの状態が原因でWeb Servicesが要求を実行できません。	○
424 Failed Dependency	Web Services Proxyでは、要求されたストレージシステムに現在アクセスできないことを示すために使用されます。したがって、Web Servicesは要求を実行できません。	×
429 Too Many Requests	要求の上限を超えたため、あとで再試行する必要があります。	×

HTTPステータスコード

説明

JSON本文

200 OK

処理に成功したことを示します。

○

201 Created

オブジェクトが作成されたことを示します。このコードは、ステータス200の代わりにごくまれに使用されます。

○

202 Accepted

要求は非同期要求としての処理を承認されましたが、実際の結果を取得するためには再度要求が必要です。

○

203 Non-Authoritative Information

200と同様ですが、Web Servicesはデータが最新であることを保証できません（その時点でキャッシュデータしか使用できない場合など）。

○

204 No Content

処理には成功しましたが、応答本文はありません。

400 Bad Request

要求のJSON本文が有効でないことを示します。

401 Unauthorized

認証に失敗したことを示します。クレデンシャルが指定されていないか、ユーザー名またはパスワードが無効です。

403 Forbidden

認証に失敗したことを示します。認証されたユーザーに要求したエンドポイントにアクセスする権限がありません。

404 Not Found

要求されたリソースが見つからなかったことを示します。このコードは、識別子で要求されたAPIやリソースが存在しない場合に使用されます。

422 Unprocessable Entity

要求の形式には問題はありませんが、入力パラメーターが無効であるか、ストレージシステムの状態が原因でWeb Servicesが要求を実行できません。

○

424 Failed Dependency

Web Services Proxyでは、要求されたストレージシステムに現在アクセスできないことを示すために使用されます。したがって、Web Servicesは要求を実行できません。

429 Too Many Requests

要求の上限を超えたため、あとで再試行する必要があります。

サンプルスクリプト

GitHubに、SANtricity Web Services APIの使用方法を示すサンプルスクリプトをまとめたリポジトリが用意されています。