- ホストメタデータの取得
- ホストメタデータの登録・更新
- ホストメタデータの削除
- ホストメタデータの一覧
- サービスメタデータの取得
- サービスメタデータの登録・更新
- サービスメタデータの削除
- サービスメタデータの一覧
- ロールメタデータの取得
- ロールメタデータの登録・更新
- ロールメタデータの削除
- ロールメタデータの一覧
メタデータ
このAPIを用いると、ホスト・サービス・ロールに任意のJSONデータを登録できます。管理用IDや、その他運用上の管理データなど、様々な情報を登録してご利用いただけます。
ネームスペースとは、メタデータの種類を特定する識別子です。例えばprojectやenvironmentなど、一貫した識別子を用いることを推奨します。メタデータの取得・登録・更新・削除のエンドポイントは一貫して以下のURLとなっています。
/api/v0/hosts/<hostId>/metadata/<namespace>
このエンドポイントにJSON (オブジェクト・配列・文字列・数字・真偽値・null) を登録し、取得できます。
{ "type": 12345, "region": "jp", "env": "staging", "instance_type": "c4.xlarge" }
ネームスペースにはアルファベットと数字、_、-を使用できます ([-a-zA-Z0-9_]+)。ただしmackerelから始まるネームスペースは、Mackerelのシステムが利用します。
ホストメタデータの取得
登録されたメタデータを取得します。
GET
/api/v0/hosts/<hostId>/metadata/<namespace>
APIキーに必要な権限
- Read
応答
登録されているデータのJSONが返されます。
レスポンスヘッダのLast-Modified にはメタデータの最終更新日時が設定されています。
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 400 | ホストが退役して一週間以上経過している時 |
| 404 | ホストが存在しない時 |
| 404 | ホストに指定されたメタデータが存在しない時 |
ホストメタデータの登録・更新
任意のJSONをホストのメタデータとして登録と更新を行います。
PUT
/api/v0/hosts/<hostId>/metadata/<namespace>
APIキーに必要な権限
- Read
- Write
入力
任意のJSONを指定できます。ただしデータのサイズは100KBまでに制限されています。
応答
{ "success": true }
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 400 | ホストがすでに退役している時 |
| 400 | ネームスペースが不正な値の時 |
| 400 | ホストあたりのメタデータの制限 (1ホストあたり50個) を超過して登録しようとした時 |
| 404 | ホストが存在しない時 |
| 403 | APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合 |
| 413 | メタデータが100KBを超過している時 |
ホストメタデータの削除
DELETE
/api/v0/hosts/<hostId>/metadata/<namespace>
APIキーに必要な権限
- Read
- Write
応答
成功時
{ "success": true }
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 400 | ホストがすでに退役している時 |
| 404 | ホストが存在しない時 |
| 404 | ホストに指定されたメタデータが存在しない時 |
| 403 | APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合 |
ホストメタデータの一覧
GET
/api/v0/hosts/<hostId>/metadata
APIキーに必要な権限
- Read
応答
成功時
{ "metadata": [<metadata>, <metadata>, ...] }
<metadata> は以下のキーを持つオブジェクト
| KEY | TYPE | DESCRIPTION |
|---|---|---|
namespace |
string | ネームスペース |
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 400 | ホストが退役して一週間以上経過している時 |
| 404 | ホストが存在しない時 |
サービスメタデータの取得
登録されたメタデータを取得します。
GET
/api/v0/services/<serviceName>/metadata/<namespace>
APIキーに必要な権限
- Read
応答
登録されているデータのJSONが返されます。
レスポンスヘッダのLast-Modified にはメタデータの最終更新日時が設定されています。
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 404 | サービスが存在しない時 |
| 404 | サービスに指定されたメタデータが存在しない時 |
サービスメタデータの登録・更新
任意のJSONをサービスのメタデータとして登録と更新を行います。
PUT
/api/v0/services/<serviceName>/metadata/<namespace>
APIキーに必要な権限
- Read
- Write
入力
任意のJSONを指定できます。ただしデータのサイズは100KBまでに制限されています。
応答
{ "success": true }
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 400 | ネームスペースが不正な値の時 |
| 400 | サービスあたりのメタデータの制限 (1サービスあたり50個) を超過して登録しようとした時 |
| 404 | サービスが存在しない時 |
| 403 | APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合 |
| 413 | メタデータが100KBを超過している時 |
サービスメタデータの削除
DELETE
/api/v0/services/<serviceName>/metadata/<namespace>
APIキーに必要な権限
- Read
- Write
応答
成功時
{ "success": true }
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 404 | サービスが存在しない時 |
| 404 | サービスに指定されたメタデータが存在しない時 |
| 403 | APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合 |
サービスメタデータの一覧
GET
/api/v0/services/<serviceName>/metadata
APIキーに必要な権限
- Read
応答
成功時
{ "metadata": [<metadata>, <metadata>, ...] }
<metadata> は以下のキーを持つオブジェクト
| KEY | TYPE | DESCRIPTION |
|---|---|---|
namespace |
string | ネームスペース |
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 404 | サービスが存在しない時 |
ロールメタデータの取得
登録されたメタデータを取得します。
GET
/api/v0/services/<serviceName>/roles/<roleName>/metadata/<namespace>
APIキーに必要な権限
- Read
応答
登録されているデータのJSONが返されます。
レスポンスヘッダのLast-Modified にはメタデータの最終更新日時が設定されています。
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 404 | サービス・ロールが存在しない時 |
| 404 | ロールに指定されたメタデータが存在しない時 |
ロールメタデータの登録・更新
任意のJSONをロールのメタデータとして登録と更新を行います。
PUT
/api/v0/services/<serviceName>/roles/<roleName>/metadata/<namespace>
APIキーに必要な権限
- Read
- Write
入力
任意のJSONを指定できます。ただしデータのサイズは100KBまでに制限されています。
応答
{ "success": true }
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 400 | ネームスペースが不正な値の時 |
| 400 | ロールあたりのメタデータの制限 (1ロールあたり10個) を超過して登録しようとした時 |
| 404 | サービス・ロールが存在しない時 |
| 403 | APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合 |
| 413 | メタデータが100KBを超過している時 |
ロールメタデータの削除
DELETE
/api/v0/services/<serviceName>/roles/<roleName>/metadata/<namespace>
APIキーに必要な権限
- Read
- Write
応答
成功時
{ "success": true }
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 404 | サービス・ロールが存在しない時 |
| 404 | ロールに指定されたメタデータが存在しない時 |
| 403 | APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合 |
ロールメタデータの一覧
GET
/api/v0/services/<serviceName>/roles/<roleName>/metadata
APIキーに必要な権限
- Read
応答
成功時
{ "metadata": [<metadata>, <metadata>, ...] }
<metadata> は以下のキーを持つオブジェクト
| KEY | TYPE | DESCRIPTION |
|---|---|---|
namespace |
string | ネームスペース |
失敗時
| STATUS CODE | DESCRIPTION |
|---|---|
| 404 | サービス・ロールが存在しない時 |
