メタデータ

メタデータ

この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&gt

APIキーに必要な権限

  • Read

応答

登録されているデータのJSONが返されます。
レスポンスヘッダのLast-Modified にはメタデータの最終更新日時が設定されています。

失敗時
STATUS CODE DESCRIPTION
400 ホストが退役して一週間以上経過している時
404 ホストが存在しない時
404 ホストに指定されたメタデータが存在しない時

ホストメタデータの登録・更新

任意のJSONをホストのメタデータとして登録と更新を行います。

PUT /api/v0/hosts/<hostId>/metadata/<namespace&gt

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&gt

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&gt

APIキーに必要な権限

  • Read

応答

登録されているデータのJSONが返されます。
レスポンスヘッダのLast-Modified にはメタデータの最終更新日時が設定されています。

失敗時
STATUS CODE DESCRIPTION
404 サービスが存在しない時
404 サービスに指定されたメタデータが存在しない時

サービスメタデータの登録・更新

任意のJSONをサービスのメタデータとして登録と更新を行います。

PUT /api/v0/services/<serviceName>/metadata/<namespace&gt

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&gt

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&gt

APIキーに必要な権限

  • Read

応答

登録されているデータのJSONが返されます。
レスポンスヘッダのLast-Modified にはメタデータの最終更新日時が設定されています。

失敗時
STATUS CODE DESCRIPTION
404 サービス・ロールが存在しない時
404 ロールに指定されたメタデータが存在しない時

ロールメタデータの登録・更新

任意のJSONをロールのメタデータとして登録と更新を行います。

PUT /api/v0/services/<serviceName>/roles/<roleName>/metadata/<namespace&gt

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&gt

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 サービス・ロールが存在しない時