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

HTTPメソッド

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

JSON

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

リンク

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

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

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

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

詳細については、「 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（整形表示）

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

curl --user '{PUBLIC-KEY}:{PRIVATE-KEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://cloud.mongodb.com/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
}

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

認証

Cloud Manager APIは、リクエストを認証するために 2 つの方法（ APIキーまたはサービス アカウント）のいずれかを使用します。これにより、ユーザー名とパスワードとして機能するキーとアクセス トークンがネットワーク経由で送信されることがなくなります。 使用方法の詳細については、「 プログラムによるCloud Managerへのアクセス 」を参照してください。

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

オートメーション

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

レート制限

特定のリソースには、レート制限が適用されます。

レートが制限されているリソースの場合、Cloud Manager はプロジェクト ごとに 1 分あたり最大 100 個のリクエストを許可します。 公開APIキーは Cloud Manager ユーザーに割り当てられますが、そのユーザーは複数のプロジェクトにアクセスできることに注意してください。

レート制限を超えると、 APIはHTTP 429 Too Many Requests応答コードを返します。

詳細情報

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