重要
それぞれの Atlas Administration API には独自のリソースがあり、初期設定が必要です。
Atlas Administration API サーバーには、パブリック インターネット経由でのみアクセスできます。ネットワーク ピアリングやプライベートエンドポイントを使用した接続では Atlas Administration API を利用できません。
詳細については、 「プログラムによる Atlas へのアクセス」を参照してください。
Atlas Administration API は、REST アーキテクチャ スタイルの原則に従い、Atlas の機能へのプログラムによるアクセスを可能にする多数の内部リソースを公開します。詳細については、「Atlas Administration API リファレンス」を参照してください。
Atlas へのプログラムによるアクセスの付与
次の 2 つの認証方法のいずれかを使用して、組織またはプロジェクトへのプログラムによるアクセスを許可できます。
サービス アカウント | API キー |
|---|---|
業界標準の OAuth 2.0 プロトコルを クライアント認証情報フローと併用する Atlas で認証を受ける新たな方法。 | HTTPダイジェスト認証を使用する Atlas へのレガシー認証方法。 |
サービスアカウントを作成したら、そのクライアント ID とシークレットを使用してアクセス トークンを生成し、API リクエストを認証します。アクセス トークンは、OAuth 2.0 仕様に従って 1 時間（3600 秒）のみ有効です。アクセス トークンの有効期限が切れると、漏洩したアクセス トークンを時間制限なく使用できるようなリプレイ攻撃を防ぐことができます。 | Atlas は、ナンスと呼ばれる一意の値を使用して公開キーと秘密キーをハッシュします。ナンスは HTTP ダイジェスト認証仕様に従って、短期間のみ有効です。これはリプレイ攻撃を防ぐためのもので、ナンスをキャッシュして永久に使用することはできません。 |
Atlas のロールは、サービスアカウントがアクセス トークンを使用して実行できる操作を制限します。アクセス トークンがエラーなしで API エンドポイントを呼び出せるように、ユーザーの場合と同様にサービスアカウントにロールを付与する必要があります。 | Atlas ロールは、API キーが実行できる操作を制限します。API キーで、エラーなく API エンドポイントを呼び出せるようにするには、ユーザーの場合と同様に API キーにロールを付与する必要があります。 |
Atlas は多くのリソースをプロジェクトにバインドします。多くの API リソース URL は | Atlas は多くのリソースをプロジェクトにバインドします。多くの API リソース URL は |
各サービスアカウントは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトへのアクセスをサービスアカウントに許可できます。 | 各 API キーは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトに API キーによるアクセスを許可できます。 |
サービスアカウントまたはそのアクセス トークンを使用して、Atlas UI から Atlas にログインすることはできません。 | API キーを使用して Atlas UI 経由で Atlas にログインすることはできません。 |
オプション: Atlas Administration API の IP アクセス リストを要求する
Atlas UI を使用して組織を作成すると、Atlas ではデフォルトで、API IP アクセス リスト機能が有効になります。これにより、API リクエストは、IP アクセス リストで指定したロケーション ベースの IP または CIDR アドレスからのものに限定されます。Atlas Administration API に IP アクセス リスト エントリなしでリクエストを行うと、サーバーは 403 ステータスコードで応答します。
この機能を無効にすると、IP アクセスリストが空である限り、インターネット上の任意のアドレスから API リクエストを行うことができます。IP アクセス リスト エントリを追加すると、その IP アドレスからのリクエストのみが許可されます。
組織の作成後、すべての Atlas Administration API リクエストに対して IP アクセス リストを要求するように組織を設定するには、次の手順を実行します。
Atlas で、 Organization Settings ページに移動します。
警告: ナビゲーションの改善が進行中
現在、新しく改良されたナビゲーション エクスペリエンスを導入中です。次の手順が Atlas UI の表示と一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
[Organizations] メニューの横にある [Organization Settings] アイコンをクリックします。
[ Organization Settings ]ページが表示されます。
組織へのプログラムによるアクセスの付与
サービス アカウントまたは API キーを通じて組織へのプログラムによるアクセスを許可するには、以下の手順を実行します。これら 2 つの認証方法の詳細については、「Atlas Administration API 認証」を参照してください。
必要なアクセス権
次のアクションを実行するには、Atlas に対する Organization Owner アクセス権が必要です。
Atlas で、Organization Access Manager ページに移動します。
警告: ナビゲーションの改善が進行中
現在、新しく改良されたナビゲーション エクスペリエンスを導入中です。次の手順が Atlas UI の表示と一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
サービスアカウント情報を入力します。
Nameと入力します。
Descriptionと入力します。
Client Secret Expiration メニューから期間を選択します。
[Organization Permissions] メニューから、サービスアカウントの新しいロールを選択します。
Atlas Administration API を使用して、組織のサービスアカウントを作成できます。
サービスアカウントを作成したら、出力から {CLIENT-ID} と {CLIENT-SECRET} をコピーして保存します。これは次の例のようになります。クライアント シークレットをすべて見ることができるのはこの時だけです。この情報は、API リクエストを行う際に必要になります。
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
API キーの作成
Atlas CLI を使用して組織で API キーを作成するには、次のコマンドを実行します。
atlas organizations apiKeys create [options]
コマンド構文とパラメーターの詳細については、Atlas CLI ドキュメントの「atlas organizations apiKeys create」を参照してください。
APIキーのAPIアクセス リスト エントリの追加
Atlas CLI を使用して API キーの IP アクセス リスト エントリを作成するには、次のコマンドを実行します。
atlas organizations apiKeys accessLists create [options]
コマンド構文とパラメーターの詳細については、Atlas CLI ドキュメントの「atlas organizations apiKeys accessLists create」を参照してください。
Atlas で、Organization Access Manager ページに移動します。
警告: ナビゲーションの改善が進行中
現在、新しく改良されたナビゲーション エクスペリエンスを導入中です。次の手順が Atlas UI の表示と一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
API Key Information を入力します。
Descriptionと入力します。
Organization Permissions メニューで、API キーの新しいロールを選択します。
プロジェクトへのプログラムによるアクセスの付与
サービス アカウントまたはAPIキーを使用して、プロジェクトへのプログラムによるアクセスを許可するには、次の手順に従います。これら 2 つの認証方法の詳細については、Atlas Administration API認証 を参照してください。
必要なアクセス権
サービスアカウントにプロジェクトへのアクセス権を付与するには、そのプロジェクトを所有する組織への Organization Owner アクセス権が必要です。
API キーにプロジェクトへのアクセス権を付与するには、そのプロジェクトに対する Project Owner アクセス権が必要です。
プロジェクトへの既存の組織アクセス権の割り当て
組織用の API キーまたはサービス アカウントを作成済みの場合は、それらをプロジェクトに割り当てて、そのプロジェクトに Atlas Administration API へのアクセス権を付与できます。
警告
組織サービスアカウントをプロジェクトに割り当てると、Project Owner はシークレットのローテーションや IP アクセス リストの更新などを含め、サービスアカウントを管理できます。
Atlas で、Project Access Manager ページに移動します。
警告: ナビゲーションの改善が進行中
現在、新しく改良されたナビゲーション エクスペリエンスを導入中です。次の手順が Atlas UI の表示と一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
プロジェクト ロールをサービスアカウントに割り当てます。
表示されるメニューで、サービスアカウントの新しいロールを選択します。
Atlas Administration API を使用して、既存のサービスアカウントにプロジェクトへのアクセス権を付与できます。
Atlas CLI を使用してプロジェクトに API キーを割り当てるには、次のコマンドを実行します。
atlas projects apiKeys assign <ID> [options]
コマンド構文とパラメーターの詳細については、Atlas CLIドキュメントの「atlas projects apiKeys assign」を参照してください。
Atlas UI を使用して組織 API キーをプロジェクトに割り当てるには、次のようにします。
Atlas で、Project Access Manager ページに移動します。
警告: ナビゲーションの改善が進行中
現在、新しく改良されたナビゲーション エクスペリエンスを導入中です。次の手順が Atlas UI の表示と一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API キーをプロジェクトに追加します。
フィールドに公開キーを入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
プロジェクトからのプロジェクト アクセス権の追加
組織用のサービス アカウントまたは API キーをまだ作成していない場合は、プロジェクト用に作成して、そのプロジェクトに Atlas Administration API へのアクセス権を付与できます。プロジェクト用に作成したサービス アカウントまたは API キーは、Organization Member 権限を持つ親組織に自動的に追加されます。
Atlas UI を使用してプロジェクトのサービスアカウントを作成する場合
Atlas で、Project Access Manager ページに移動します。
警告: ナビゲーションの改善が進行中
現在、新しく改良されたナビゲーション エクスペリエンスを導入中です。次の手順が Atlas UI の表示と一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
サービスアカウント情報を入力します。
Nameと入力します。
Descriptionと入力します。
Client Secret Expiration メニューから期間を選択します。
[Project Permissions（プロジェクト権限）] メニューから、サービスアカウントの新しいロールを選択します。
Atlas Administration API を使用して、プロジェクトのサービスアカウントを作成できます。
サービスアカウントを作成したら、出力から {CLIENT-ID} と {CLIENT-SECRET} をコピーして保存します。これは次の例のようになります。クライアント シークレットをすべて見ることができるのはこの時だけです。この情報は、API リクエストを行う際に必要になります。
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
Atlas CLI を使用してプロジェクトの API キーを作成するには、次のコマンドを実行します。
atlas projects apiKeys create [options]
コマンド構文とパラメーターの詳細については、Atlas CLI ドキュメントの「atlas projects apiKeys create」を参照してください。
プロジェクトの API キーを作成したら、Atlas UI を使用して API アクセスリストエントリを追加します。API アクセス リストを設定するまで、プロジェクトの API キーは使用できません。
注意
Atlas CLI の制限
Atlas CLI を使用してプロジェクト API キーの API アクセスリストを編集することはできません。
Atlas UI を使用して API アクセスリストのエントリを追加する場合
Atlas UI を使用してプロジェクトの API キーを作成する場合
Atlas で、Project Access Manager ページに移動します。
警告: ナビゲーションの改善が進行中
現在、新しく改良されたナビゲーション エクスペリエンスを導入中です。次の手順が Atlas UI の表示と一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API Key Information を入力します。
[Create API Key] ページで次を行います。
Descriptionと入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
API リクエストを行う
Atlas Administration API は、サービス アカウントまたは API キーという 2 つの認証方法のいずれかを使用してリクエストを認証します。次の手順を完了するには、希望する認証方法を構成するときに保存したキーまたはシークレットが必要です。
すべての Atlas Administration API エンドポイントには次のベース URL があります。
https://cloud.mongodb.com/api/atlas/<version>
重要
MongoDB は、セキュリティを強化するために HTTPS URL を使用します。 HTTP URL を使用すると、301 ステータス コードが返されます。
サービスアカウントを使用して API リクエストを行うには、サービスアカウントを使用してアクセス トークンを生成し、そのアクセス トークンをリクエストで使用します。
サービスアカウントのクライアント シークレットを検索します。
サービスアカウントの作成直後に保存した、mdb_sa_sk_ で始まるクライアント シークレットを見つけます。クライアント シークレットを表示できるのは、このときだけです。クライアント シークレットを保存しなかった場合は、新しいクライアント シークレットを生成する必要があります。
アクセス トークンをリクエストします。
次の例の {BASE64-AUTH} を前のステップの出力に置き換え、実行します。
1 curl --request POST \ 2 --url https://cloud.mongodb.com/api/oauth/token \ 3 --header 'accept: application/json' \ 4 --header 'cache-control: no-cache' \ 5 --header 'authorization: Basic {BASE64-AUTH}' \ 6 --header 'content-type: application/x-www-form-urlencoded' \ 7 --data 'grant_type=client_credentials'
{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImYyZjE2YmE4LTkwYjUtNDRlZS1iMWYwLTRkNWE2OTllYzVhNyJ9.eyJpc3MiOiJodHRwczovL2Nsb3VkLWRldi5tb25nb2RiLmNvbSIsImF1ZCI6ImFwaTovL2FkbWluIiwic3ViIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImNpZCI6Im1kYl9zYV9pZF82NjI4MWJjNjAzYTcxYTQzMGI5MDZlZjciLCJhY3RvcklkIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImlhdCI6MTcxMzkwNTM1OSwiZXhwIjoxNzEzOTA4OTU5LCJqdGkiOiI4ZTg1MTM3YS0wZGU1LTQ0N2YtYTA0OS1hMmVmNTIwZGJhNTIifQ.AZSFvhcjwVcJYmvW6E_K5UnDmeiX2sJgL27vo5ElzeBuPawRciKkn6ervZ6IpUTx2HHllGgAAMmhaP9B66NywhfjAXC697X9KcOzm81DTtvDjLrFeRSc_3vFmeGvfUKKXljEdWBnbmwCwtBlO5SJuBxb1V5swAl-Sbq9Ymo4NbyepSnF","expires_in":3600,"token_type":"Bearer"}%
重要
アクセス トークンは 1 時間（3600 秒）有効です。アクセス トークンを更新することはできません。このアクセス トークンの有効期限が切れたら、この手順を繰り返して新しいアクセス トークンを生成します。
API 呼び出しを行います。
次の例の {ACCESS-TOKEN} を前のステップの出力に置き換えます。
次のサンプル GET リクエストは、組織内のすべてのプロジェクトを返します。
curl --request GET \ --url https://cloud.mongodb.com/api/atlas/v2/groups \ --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header 'Accept: application/vnd.atlas.2023-02-01+json' \ --header 'Content-Type: application/json'
次のサンプル POST リクエストは、リクエスト本文を受け取り、組織内に MyProject という名前のプロジェクトを作成します。
curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2023-02-01+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
リクエストは次の例のようになります。ここで、{PUBLIC-KEY} は API 公開キー、{PRIVATE-KEY} は対応する秘密キーです。Atlas Administration API を通じて利用可能なエンドポイントを調べるには、MongoDB の Postman ワークスペースを使用できます。
次のサンプル GET リクエストは、組織内のすべてのプロジェクトを返します。
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v2/groups"
次のサンプル POST リクエストは、リクエスト本文を受け取り、組織内に MyProject という名前のプロジェクトを作成します。
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
あるいは、 OpenAPI v3 仕様をサポートする任意のツールを使用して、コードサンプルやモック サーバーを生成することもできます。例、Atlas Admin API仕様 を Postman にインポートしてcurl コマンドを生成できます。
警告
Postman でHTTP URLを使用すると、期待どおり、301 ステータス コードが返されます。ただし、このシナリオでは、Postman は HTTPS でリクエストを自動的に再試行する可能性がありますが、同時に再試行リクエストからヘッダーとボディを削除します。これにより、301 ではなく 401 ステータス コードが返されるため、リクエストが失敗した理由を判断するのが困難になります。
Postman を使用して curl コマンドを生成するには、次のようにします。
MongoDB Atlas Administration API ドキュメント で、[Download（ダウンロード）] ボタンを右クリックしてリンクをコピーします。
次のステップ
Atlas Administration API の詳細については、「Atlas Administration API リファレンス」を参照してください。
プログラムによる Atlas Administration API へのアクセスを管理するには、次のいずれかの手順を参照してください。