Cloud Manager パブリックAPIは、 RESTアーキテクチャの原則に従い、Cloud Manager の機能へのプログラムによるアクセスを提供する内部リソースを公開します。
Web インターフェースを通じて行われた変更と同様、API を通じて行われた変更には Cloud Manager価格が適用されます。 サーバーを追加して料金が発生する場合は、Cloud Managerに登録されている有効なクレジットカードが必要です。そうしないと、アカウントがロックされる可能性があります。
APIには、次の機能があります。
- JSONエンティティ
- すべてのエンティティはJSONで表現されます。
- ブラウザ可能なインターフェース
- 一貫性のあるリンク メカニズムを使用すると、ルート リソースから開始し、関連するリソースへのリンクを追跡することで、API 全体をブラウザできます。
- ユーザー アクセス制御
各 Cloud Manager ユーザーのAPI機能は、 Cloud Manager ロールが付与する権限と一致します。
例
Project Read Onlyロールを持つユーザーは、Cloud Manager UI でもAPIでも、そのプロジェクト内のリソースを変更できません。- APIネットワーク アクセス リスト
Cloud Manager APIは、 API アクセス リストを通じて Cloud Manager Administration API へのアクセスを保護できます。 このリストは、特定の IP アドレスまたは CIDR アドレスへの API へのアクセスを制限します。各APIキーには、独自の Cloud Manager Administration API アクセス リストがあります。 Cloud Manager UI を使用して新しい組織を作成すると、MongoDB Atlas ではデフォルトでAPIアクセス リストの要求が有効になります。
詳細については、「 （任意）組織の API アクセス リストが必要 」を参照してください。
- HTTPS Only
- HTTPS 経由でのみ API にアクセスできるため、ネットワーク経由で送信されるすべてのデータは TLS を使用して完全に暗号化されます。
HTTPメソッド
すべてのリソースは、次の一般的なHTTPメソッドのサブセットをサポートしています。
方式 | 目的 |
|---|---|
| リソースのJSON表現を取得します。 |
| 指定されたJSON表現を使用して新しいリソースを作成します。 |
| リソースを指定されたJSON表現で置き換えます。 |
| 提供されたJSON表現を使用して、リソース内の指定されたフィールドを更新します。 |
| リソースを削除します。 |
| リソースのJSON表現なしでレスポンスヘッダーを取得します。 |
JSON
すべてのエンティティはJSONで表されます。 リクエストと応答の規則には次のルールが適用されます。
リクエストルール
- 正しいコンテンツタイプヘッダーの適用
POSTまたはPUT経由でサーバーにJSONを送信する場合は、必ず正しいコンテンツタイプのリクエストヘッダーを指定してください。Content-Type: application/json- ISO8601 string として日付を設定
When sending dates to the server (as query parameters or fields in
POSTorPATCHrequest entities), use dates formatted according to the ISO 8601 standard. If you don't specify a time zone, Cloud Manager assumes UTC. Include a time zone designator to avoid any ambiguity.例
2018 年 9 月 27 日は
2018-09-27として表されます。2018 年 9 月 27 日、午前 4 時 00分 EDT は（タイムゾーンとともに）
2018-09-27T16:00-04:00として表されます。
場合によっては、タイムスタンプがBSONタイムスタンプのJSON表現として返される場合があり、特にバックアップリソースに含まれます。 BSONタイムスタンプのこの表現は、2 つのフィールドを持つオブジェクトとしてJSON ドキュメント を提供します。
フィールド定義dateUNIXエポック からの秒数
increment特定の秒内の操作の増分 32 ビット整数序数。
例
2018 年 9 月 27 日、午前 4:00、EDT の 3 回目の操作は、次のように表されます（タイムゾーン）
{ date: 2018-09-27T16:00-04:00, increment: 3 }
応答規則
- 無効なフィールドを拒否
無効なフィールドは無視されるのではなく拒否されます。
例
新しいエンティティを作成しようとし、フィールドの 1 つのスペルをうっかり間違えた場合、または既存のエンティティをアップデートして変更できないフィールドを含めようとすると、 Cloud Manager はHTTP 400 ステータス コードと以下を示すエラーメッセージを返します。フィールドが無効でした。
- 日付を ISO8601 string として返します
- すべての日付は、UTC で指定された ISO 8601 形式の文字列として返されます。
- 単位を曖昧にするフィールドにラベルを付ける
特定の単位の数値を含むフィールドには、使用される単位を明確に区別するために名前が付けられます。
例
ホストのアップタイムはミリ秒単位で返されるため、ホスト エンティティ フィールドの名前は
uptimeMsecです。- 他の値がないフィールドのデフォルト値を返します
現在の値がないフィールドは、適切なデフォルト値とともに返されます。
例
Cloud Manager には新しく検出されたホストの統計がないため、統計関連のフィールドの値はゼロになります。
認識可能なデフォルト値を持たないフィールドは、エンティティから省略されます。
例
認証を使用していないホストでは、返されるエンティティから
usernameフィールドが省略されます。- アルファベット順のフィールドを返します
- Cloud Manager が返すJSONドキュメント内のフィールドはアルファベット順です。 順序が変更される可能性があります。 フィールドの順序に依存しないでください。
リンク
各リソースには、サブリソースや関連リソースへの 1 つ以上のリンクが含まれています。
例
ホストには、属するプロジェクト、属するレプリカセットなどへのリンクがあります。
リンクは、リンク関係オブジェクトの配列であるエンティティのlinksフィールドに配置されます。 各リンク関係には 2 つのフィールドがあります。
フィールド | 定義 |
|---|---|
| 関係の名前（またはタイプ）。 これらの多くは拡張関係タイプと見なされ、 |
| ターゲットURL 。 |
すべてのエンティティには、self というリンク関係が少なくとも 1 つ含まれています。これはつまり独自のURLです。エンティティがリストの一部である場合（つまり、プロジェクト内のすべてのホストをリクエストする場合）、そのエンティティには self リンク関係のみが含まれます。
例
これは、いくつかのリンクを含むhostリソースの一部です。
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 リンク仕様 」を参照してください。
注意
Web リンク仕様 ではHTTPレスポンス ヘッダーにリンクを含めるための形式について説明されていますが、これは必須ではありません。APIを簡単に閲覧できるようにするには、レスポンス ヘッダーではなくレスポンス本体にリンクを含めます。
リスト
一部のリソースはエンティティのリストを返します。
例
プロジェクト内のすべてのホストのリストをリクエストできます。
応答でエンティティのリストが要求される場合、結果は 2 つのクエリ パラメータに囲まれたバッチで返されます。
フィールド | 定義 |
|---|---|
| ページ番号（1 から始まる）。 指定しない場合、デフォルトは 1 です。 |
| 1 ページあたりに返す項目の数は最大 500 です。 指定しない場合、デフォルトは 100 です。 |
応答エンティティには、次の 3 つのフィールドが含まれています。
フィールド | 定義 |
|---|---|
| 結果セット全体内の項目の合計数。 たとえば、プロジェクトに合計57のホストがあり、 |
| 結果セット 。これはエンティティ ドキュメントの配列です。 |
| 1 から 3 のリンク関係が含まれています。
|
If you make a request for a list of entities and there are no results, then the API responds with an HTTP 200 status code and an empty results array. It does not respond with a 404 in this case, since the list of entities may not be empty at some point in the future.
存在しないコンテキストでエンティティのリスト（つまり、存在しないプロジェクトのホストのリスト）をリクエストした場合、これはHTTP 404 応答ステータスになります。
例
これは、合計で 57 ホストを含むプロジェクト内の 10 ホストの 2 ページのHTTPレスポンスです。
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ドキュメント内の追加の情報レイヤーです。
By default, the API does not include the response in an envelope. To request one, simply add the query parameter envelope=true.
単一のエンティティを含む応答の場合、エンベロープには 2 つのフィールドが含まれます。
フィールド | 定義 |
|---|---|
| HTTP status code. |
| 要求されたエンティティ。 |
エンティティのリストを含む応答の場合、結果をラップするエンベロープはすでにあるため、この場合はクエリ パラメータとして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"
注意
このドキュメントのすべての例は、わかりやすくするためにpretty-printed JSONを示していますが、一部のサンプルURLにはこの追加のクエリパラメータが含まれていない場合があります。
応答コード
応答では、次のような標準のHTTP応答コードが使用されます。
コード | 意味 | ノート |
|---|---|---|
200 | OK | リクエストは成功しました。 これは、 |
201 | 作成済み | 新しいリソースが作成されました。 これは、 |
202 | 承認済み | 非同期操作のリクエストが受け入れられました。 |
400 | 無効なリクエスト | クライアント リクエストで問題が発生しました。 |
401 | 許可されていない | 認証は必要ですが、リクエストに含まれていませんでした。 通常、これはリクエストからダイジェスト認証情報が省略されたか、提供された認証情報が正しくないか、特定のAPIキーに関連付けられたユーザーが要求されたリソースにアクセスできないことを意味します。 |
403 | Forbidden | 指定されたリソースへのアクセスは許可されていません。 |
404 | 見つかりません | 要求されたリソースが存在しない。 |
405 | メソッドは許可されていません | HTTPメソッドは指定されたリソースではサポートされていません。 各リソースがサポートするのはHTTPメソッドのサブセットのみであることに注意してください。 たとえば、ルートリソースを |
409 | 競合 | これは通常、そのプロパティの同じ値を持つ既存のエンティティがすでに存在する場合に一意なエンティティのプロパティを作成または変更するためのリクエストに対する応答です。 たとえば、既存のプロジェクトと同じ名前のプロジェクトを作成しようとすると、リクエストは失敗します。 |
5x | さまざまなサーバーエラー | 予期しない問題が発生しました。 後でもう一度お試しください。Cloud Manager サポートへの通知を検討してください。 |
Errors
リクエストの結果としてエラーが発生した場合、レスポンス本文には、何が起こるかを示す追加の詳細が記載されたJSONドキュメントが含まれます。 ドキュメントには、次の 5 つのフィールドが含まれています。
フィールド | データ型 | 定義 |
|---|---|---|
| string | APIリクエスト エラーの、人間が判読可能な説明。 |
| integer | HTTP ステータス コード。 |
| string | Cloud Manager 管理 API エラー コード に示される、 API リクエスト エラーを表す名前付き定数。 |
| 文字列の配列 | APIリクエストで渡されるパラメータのリスト。 |
| string | HTTP ステータス コードの定義。 |
例
Cloud Manager は、誤った形式のリクエストに対して次のレスポンス本体を返します。
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へのプログラムによるアクセス 」を参照してください。
サービス アカウント | API キー |
|---|---|
クライアント認証情報フローを持つ業界標準の OAuth.2 0プロトコルを使用してCloud Managerに認証する新しい方法。 | Cloud ManagerHTTPHTTPダイジェスト認証を使用するCloud Managerへのレガシー認証方法。 |
サービス アカウントを使用すると、権限を管理し、アクセス トークンを作成できます。 サービス アカウントには、アクセス トークンを作成するためのユーザー名とパスワードとして機能するクライアントIDとシークレットがあります。 アクセス トークンを使用すると、 CloudAPI Cloud ManagerManagerにAPIリクエストを行うことができます。 | APIキーには、公開キーと秘密キーの 2 つの部分があります。この 2 つの部分が、 APICloud ManagerCloud ManagerにAPIリクエストを行う際に、ユーザー名およびパスワードと同じ機能を果たします。 |
After you create a service account, you'll use its client ID and secret to generate an access token, which authenticates your API requests. Access tokens are only valid for 1 hour (3600 seconds) per the OAuth 2.0 specification. Expiration of access tokens prevents replay attacks, where a leaked access token could be used without a time restriction. | Cloud Managerは、 noance と呼ばれる一意の値を使用して、公開キーと秘密キーをハッシュします。HTTPダイジェスト仕様に従って短時間のみ有効です。これはリプレイ攻撃を防ぐためのもので、期間をキャッシュして永久に使用することはできません。 |
Cloud Manager は多くのリソースをプロジェクトにバインドします。多くのAPIリソースURLは | Cloud Manager は多くのリソースをプロジェクトにバインドします。多くのAPIリソースURLは |
各サービスアカウントは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトへのアクセスをサービスアカウントに許可できます。 | 各 API キーは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトに API キーによるアクセスを許可できます。 |
一部のリソース メソッドはさらに多くのセキュリティを必要とし、リストされている IP アドレスからのみリソースへのアクセスを許可する アクセス リスト によって追加で保護されています。各ユーザーは、リソースへのアクセスを許可するIPアドレスの独自のアクセス リストを構成します。
オートメーション
オートメーション構成リソースと最新プランのオートメーションステータスの取得リソースは、プロジェクトの配置を変更し、配置ステータスを取得するためのエンドポイントを提供します。 新しいオートメーション構成を Cloud Manager に送信することで配置を変更できます。 オートメーション構成では、配置する MongoDB プロセスを説明して構成します。 Cloud Manager では、これを配置の「ターゲット 状態」と呼びます。 APIを通じて新しいオートメーション構成を送信すると、オートメーションはシステムの現在の状態を目的の状態に一致するように調整します。
重要
APIには、同時変更を防ぐための保護はありません。 2 人の管理者がそれぞれ現在のバージョンに基づく構成で開始し、独自の変更を加えてから変更を送信すると、後の変更が成功します。
レート制限
特定のリソースには、レート制限が適用されます。
レートが制限されているリソースの場合、 Cloud Manager はプロジェクトごとに 1 分あたり最大 100 のリクエストを許可します。公開APIキーはCloud Managerユーザーに割り当てられますが、そのユーザーは複数のプロジェクトにアクセスできることに注意してください。
例
A と B の 2 人のユーザーを考えてみましょう。
ユーザー A はプロジェクト X に属し、ユーザー B はプロジェクト X と Y に属しています。
午前 1 時 00分に、ユーザー A はプロジェクト X のレート制限されたリソースに 50 回のリクエストを送信し、すべてが 1 時 00 分、20 時までに完了します。
午前 1 時 00分: 30 分に、ユーザー B はプロジェクト X のレート制限されたリソースに対して 60 回のリクエストを実行しようとします。
ユーザー A はプロジェクト X の 1 時 00 分以内に 50 個のリクエストをすでに使用しているため、ユーザー B が試みた最後の 10 個のリクエストは拒否されます。 ただし、各プロジェクトが個別のリクエスト カウンターを保持しているため、ユーザー B はプロジェクト Y のレート制限されたリソースにリクエストを行うことができます。
午後 1 時 01 分になると、レート制限に使用されるリクエスト カウンターが 1 分ごとにリセットされるため、プロジェクト X へのリクエストが続行される可能性があります。
レート制限を超えると、 API はHTTP 429 Too Many Requests 応答コードを返します。
詳細情報
Cloud Manager のパブリック API で利用可能なすべてのリソースの完全なリファレンスについては、「 Cloud Manager 管理 API リソース 」を参照してください。