パブリック API プリンシパル

HTTP メソッド

すべてのリソースは、次の一般的なHTTPメソッドのサブセットをサポートしています。

JSON

すべてのエンティティはJSONで表されます。 リクエストと応答の規則には次のルールが適用されます。

リンク

各リソースには、サブリソースや関連リソースへの 1 つ以上のリンクが含まれています。

リンクは、リンク関係オブジェクトの配列であるエンティティのlinksフィールドに配置されます。 各リンク関係には 2 つのフィールドがあります。

すべてのエンティティには、 selfと呼ばれるリンク関係が少なくとも 1 つ含まれます。これはつまり、独自のURLです。 エンティティがリストの一部である場合（つまり、プロジェクト内のすべてのホストをリクエストする場合）、そのエンティティにはselfリンク関係のみが含まれます。

1
{
2
  "rel": "http://mms.mongodb.com/project",
3
  "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx"
4
  "id": "xxx",
5
  "projectId": "yyy",
6
  "hostname": "mongodb.example.com",
7
  "port": 27017,
8
  "links": [
9
    {
10
      "rel": "self",
11
      "href": "https://<ops-manager-host>/api/public/v1.0/projects/xxx/hosts/yyy"
12
    },
13
    {
14
      "rel": "http://mms.mongodb.com/project",
15
      "href": "https://<ops-manager-host>/api/public/v1.0/projects/xxx"
16
    }
17
  ]
18
}

詳細については、「 Web リンク仕様 」を参照してください。 。

リスト

一部のリソースはエンティティのリストを返します。

応答でエンティティのリストが要求される場合、結果は 2 つのクエリ パラメータに囲まれたバッチで返されます。

応答エンティティには、次の 3 つのフィールドが含まれています。

エンティティのリストのリクエストを行って結果がない場合、 APIはHTTP 200 ステータス コードと空のresults配列で応答します。 この場合、エンティティのリストが将来のある時点で空ではなくなる可能性があるため、この場合は 404 では応答しません。

存在しないコンテキストでエンティティのリスト（つまり、存在しないプロジェクトのホストのリスト）を要求した場合は、 HTTP 404 応答ステータスが返されます。

1
{
2
3
  "totalCount": 57,
4
  "results": [
5
    {
6
      "id": "yyy",
7
      "projectId": "xxx",
8
      // additional host properties...
9
    },
10
    // additional host documents...
11
  ],
12
  "links": [
13
    {
14
      "rel" : "self",
15
      "href" : "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?pageNum=2&itemsPerPage=10"
16
    },
17
    {
18
      "rel": "previous",
19
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=1"
20
    },
21
    {
22
      "rel": "next",
23
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=3"
24
    }
25
  ]
26
}

エンベロープ

一部のクライアントは、 HTTPレスポンス ヘッダーやステータス コードにアクセスできない場合があります。 この場合は、応答にenvelopeを含めることをリクエストできます。これは、通常応答 ヘッダーに含まれる関連詳細を含む、 JSONドキュメント内の追加の情報レイヤーです。

デフォルトでは、 APIのエンベロープに応答は含まれません。 リクエストするには、クエリ パラメータenvelope=trueを追加します。

単一のエンティティを含む応答の場合、エンベロープには 2 つのフィールドが含まれます。

エンティティのリストを含む応答の場合、結果をラップするエンベロープはすでにあるため、この場合はクエリ パラメータとしてenvelope=trueを指定すると、既存のエンベロープにstatusフィールドのみが追加されます。

Pretty Printing（整形表示）

デフォルトでは、MongoDB Ops Manager が返すJSONから余計な空白が削除されます。 pretty-printed JSONをリクエストするには、リクエストにpretty=trueクエリ パラメータを追加します。

curl --user '{USERNAME}:{APIKEY}' --digest \
--header 'Accept: application/json' \
--include \
--request GET "{opsManagerHost}:{Port}/api/public/v1.0?pretty=true"

応答コード

応答では、次のような標準のHTTP応答コードが使用されます。

Errors

リクエストの結果としてエラーが発生した場合、レスポンス本文には、何が起こるかを示す追加の詳細が記載されたJSONドキュメントが含まれます。 ドキュメントには、次の 5 つのフィールドが含まれています。

1
{
2
  "detail" : "Cannot find resource /api/public/v1.0/softwareComponents/version.",
3
  "error" : 404,
4
  "errorCode" : "RESOURCE_NOT_FOUND",
5
  "parameters" : [ "/api/public/v1.0/softwareComponents/version" ],
6
  "reason" : "Not Found"
7
}

コードのリストを確認するには、「 MongoDB Ops Manager Administration APIエラー コード 」を参照してください。

認証

前述のように、 MongoDB Ops Manager APIはHTTPダイジェスト認証を使用します。 ダイジェスト認証の詳細は、このドキュメントの範囲外ですが、基本的にはnoanceと呼ばれるサーバーが生成した一意の値を使用してハッシュされたユーザー名とパスワードが必要です。 ユーザー名は登録された MongoDB Ops Manager アカウントのユーザー名であり、パスワードはそのアカウントに関連付けられた公開APIキーです。

次の点に注意してください。

• サーバーが生成した noth は、リクエストを認証するためにサーバーに送り返す前にユーザー名とパスワードをハッシュするために使用されます。 noth は、 ダイジェスト認証の仕様に従って短時間のみ有効です。 これはリプレイ攻撃を防ぐためのもので、期間をキャッシュして永久に使用することはできません。

• 一部のリソース メソッドはさらに多くのセキュリティを必要とし、リストされている IP アドレスからのみリソースへのアクセスを許可する アクセス リスト によって追加で保護されています。各ユーザーは、リソースへのアクセスを許可するIPアドレスの独自のアクセス リストを構成します。

• MongoDB Ops Manager アプリケーションにはロールという概念があり、これによりユーザーが実行できる操作をよりきめ細かく制御できます。API リソースも同じ承認ルールを適用するため、API キーでアクセスできるリソースとメソッドは、関連付けられたユーザーに付与されたロールによって管理されます。

  例

  ホストをDELETEするには、リクエストの実行に使用されるAPIキーを所有するユーザーが、ホストが属するプロジェクトのProject Monitoring AdminまたはProject Ownerである必要があります。

• 次の形式の URL が示すように、多くのリソースがプロジェクト（以前は グループ と呼ばれる）に関連付けられています。

  /api/public/v1.0/groups/{PROJECT-ID}/

  これらのリソースでは、 APIキーに関連付けられたユーザーはプロジェクトのメンバーであるか、 GLOBALロールのいずれかに割り当てられている必要があります。 それ以外の場合、 MongoDB Ops ManagerアプリケーションはHTTP 401 エラーで応答します。

オートメーション

オートメーション構成リソースと最新プランのオートメーションステータスの取得リソースは、プロジェクトの配置を変更し、配置ステータスを取得するためのエンドポイントを提供します。 新しいオートメーション構成をMongoDB Ops Managerに送信することで配置を変更できます。 オートメーション構成では、配置する MongoDB プロセスを説明して構成します。 MongoDB Ops Managerでは、これを配置の「ターゲット 状態」と指します。 APIを通じて新しいオートメーション構成を送信すると、オートメーションはシステムの現在の状態を目的の状態に一致するように調整します。

詳細情報

のパブリック で利用可能なすべてのリソースの完全なリファレンスについては、「MongoDB Ops Manager AdministrationAPI リソースMongoDB Ops Manager API」を参照してください。