テナント管理APIの概要

StorageGRID Webscaleには、テナントアカウントを管理するためのREST APIが用意されています。

テナント管理APIのドキュメント

テナント管理APIは、オープンソースのAPIプラットフォームであるSwaggerを使用してAPIのドキュメントを提供しています。Swaggerでは、ユーザインターフェイスを使用してパラメータやオプションを変更した場合のAPIの動作を確認しながら、APIの開発を進めることができます。Swaggerのドキュメントは、標準的なWebテクノロジとJavaScript Object Notation（JSON）データ形式について十分理解していることを前提としています。

注意:Swaggerユーザインターフェイスを使用して実行するAPI処理はすべてライブ処理です。設定やその他のデータを誤って作成、更新、または削除しないように注意してください。

テナント管理APIのドキュメントにアクセスするには、テナント管理インターフェイスにサインインし、Webアプリケーションヘッダーで[Help] > [API Docs]を選択します。
[API Docs]メニュー項目にアクセスする方法を示すスクリーンショット

API

各REST APIコマンドは、APIのURL、HTTPアクション、必須またはオプションのURLパラメータ、および想定されるAPI応答で構成されます。

Swaggerのユーザインターフェイスでは、次の例のように、各API処理に関する詳細情報とドキュメントを参照できます。ローカルテナントユーザに関する情報を表示するには、shortNameパラメータの値としてそのユーザの一意の名前を入力し、[Try it out]をクリックします。

テナント管理APIには次のセクションが含まれています。

account – 現在のテナントアカウントに対する処理（ストレージの使用状況に関する情報の取得など）。
auth – ユーザセッション認証を実行する処理。

テナント管理APIは、Bearerトークン認証方式をサポートしています。テナントにログインするには、認証要求（POST /api/v2/authorize）のJSONの本文にユーザ名、パスワード、アカウントIDを指定します。ユーザが認証されると、セキュリティトークンが返されます。このトークンを後続のAPI要求のヘッダーで指定する必要があります（「Authorization: Bearer token」）。

認証のセキュリティ強化については、「クロスサイトリクエストフォージェリ（CSRF）の防止方法」を参照してください。
config – 製品リリースとテナント管理APIのバージョンに関連する処理。製品リリースバージョンおよびそのリリースでサポートされるAPIのメジャーバージョンを一覧表示できます。
containers – S3バケットまたはSwiftコンテナに対する処理。S3バケットおよびSwiftコンテナの整合性レベルの設定を含みます。S3バケットの場合は、オブジェクトの最終アクセス日時の更新、およびプラットフォームサービスの設定処理も含まれます。プラットフォームサービスにはCloudMirrorレプリケーション、通知、検索統合（メタデータ通知）があります。
deactivated-features – 非アクティブ化された可能性がある機能を表示する処理。
endpoints – エンドポイントを管理する処理。エンドポイントを使用することで、S3バケットは外部のサービスをStorageGRID Webscale CloudMirrorレプリケーション、通知、または検索統合に使用できます。
groups – ローカルテナントグループを管理する処理と、外部アイデンティティソースからフェデレーテッドテナントグループを取得する処理。
identity-source – 外部のIDソースを設定する処理、およびフェデレーテッドグループとユーザ情報を手動で同期する処理。
s3 – テナントユーザのS3アクセスキーを管理する処理。
users – テナントユーザを表示および管理する処理。

テナント管理APIのバージョン管理

テナント管理APIは、バージョン管理を使用して無停止アップグレードをサポートします。たとえば、次の要求URLではバージョン2のAPIが指定されています。

https://hostname_or_ip_address/api/v2/authorize

テナント管理APIで後方互換性のない変更が行われた場合は、APIのメジャーバージョンが上がります。たとえば、APIに対して互換性のない変更が行われると、バージョンが1.1から2.0に上がります。テナント管理APIで後方互換性のある変更が行われた場合は、マイナーバージョンが上がります。後方互換性のある変更には、新しいエンドポイントやプロパティの追加などがあります。たとえば、APIに対して互換性のある変更が行われると、バージョンが1.0から1.1に上がります。

StorageGRID Webscaleソフトウェアを初めてインストールした時点では、テナント管理APIの最新のバージョンのみが有効になっています。ただし、StorageGRID Webscaleを新しいメジャーバージョンにアップグレードした場合、少なくともメジャーリリース1つ分のアップグレードにおいては、古いAPIバージョンにも引き続きアクセスできます。

古い要求は、次の方法で廃止とマークされます。

応答ヘッダーが「Deprecated: true」となる。
JSON応答の本文に「deprecated: true」が追加される。

現在のリリースでサポートされているAPIバージョンの特定

サポートされているAPIのメジャーバージョンのリストを返すには、次のAPI要求を使用します。

GET https://{{IP-Address}}/api/versions
{
    "responseTime": "2016-10-03T14:49:16.587Z",
    "status": "success",
    "apiVersion": "2.0",
    "data": [
        1,
        2
    ]
}

要求のAPIバージョンの指定

APIのバージョンは、パスパラメータ（/api/v2）またはヘッダー（Api-Version: 2）を使用して指定できます。両方を指定した場合、ヘッダーの値がパスの値を上書きします。

curl https://[IP-Address]/api/v2/org/config

curl -H "Api-Version: 2" https://[IP-Address]/api/org/config