Atlas Administration API を使い始める
項目一覧
- Atlas へのプログラムによるアクセスのための OAuth 2.0認証はプレビュー機能として利用できます。
- 機能および関連するドキュメントは、プレビュー期間中にいつでも変更される可能性があります。 OAuth2.0 認証を使用するには、Atlas Administration APIへのリクエストで使用する サービス アカウントを作成します。
重要
それぞれの Atlas Administration API には独自のリソースがあり、初期設定が必要です。
Atlas Administration API サーバーには、パブリックインターネットからのみアクセスできます。Atlas Administration API は、ネットワーク ピアリングまたはプライベート エンドポイントを使用する接続では使用できません。
詳細については、 「プログラムによる Atlas へのアクセス」を参照してください。
Atlas Administration API は、 REST アーキテクチャ スタイルの原則に従い、Atlas の機能へのプログラムによるアクセスを可能にする多数の内部リソースを公開します。詳細については、 Atlas Administration API リファレンスを参照してください。
Atlas へのプログラムによるアクセスの付与
次の 2 つの認証方法のいずれかを使用して、組織またはプロジェクトへのプログラムによるアクセスを許可できます。
API キー | サービス アカウント（プレビュー） |
|---|---|
HTTPダイジェスト認証を使用する Atlas への認証のレガシー方法。 | 業界標準の OAuth 2.0 プロトコルとクライアント認証情報フロー を使用して Atlas に認証する新しい方法。現在はプレビュー段階です。 |
APIキーには、公開キーと秘密キーの 2 つの部分があります。この 2 つの部分は、Atlas に<a class=\" \" target=\" \" href=\" \"> API リクエスト を行う際のユーザー名とパスワードと同じ機能を果たします。 | |
Atlasは、ノンスと呼ばれる一意の値を使用して公開鍵と秘密鍵をハッシュします。 nonceはHTTPダイジェスト認証に従って短期間のみ有効です。 仕様。これはリプレイ攻撃を防ぐためのもので、nonce をキャッシュして永久に使用することはできません。 | サービス アカウントを作成したら、そのクライアントIDとシークレットを使用してアクセス トークンを生成し、APIリクエストを認証します。アクセス トークンは、13600OAuth2.0に従って 時間 ( 秒) のみ有効です。 仕様。アクセストークンの有効期限が切れると、漏洩したアクセストークンが時間制限なく使用できるようなリプレイ攻撃を防ぐことができます。 |
アトラスの役割は、サービスアカウントがアクセストークンを使用して実行できる操作を制限します。 アクセストークンがエラーなしでAPIエンドポイントを呼び出せるように、ユーザーと同じようにサービスアカウントにロールを付与する必要があります。 | |
Atlas は多くのリソースをプロジェクトにバインドします。 多くのAPIリソースURLは /api/atlas/<version>/groups/<GROUP-ID>/の形式に従います。ここで、<GROUP-ID> はプロジェクトIDです。これらのリソースの場合、APIキーはプロジェクトをホストする組織のメンバーである必要があります。それ以外の場合、Atlas は 401 エラーで応答します。組織レベルのAPIキーにプロジェクトへのアクセス権を付与するには、 「プロジェクトへの既存の組織アクセス権の割り当て」を参照してください。 | Atlas は多くのリソースをプロジェクトにバインドします。 多くのAPIリソースURLは /api/atlas/<version>/groups/<GROUP-ID>/の形式に従います。ここで、<GROUP-ID> はプロジェクトIDです。これらのリソースについては、サービスアカウントはプロジェクトをホストする組織のメンバーでなければなりません。 そうでない場合、Atlasは 401エラーを返します。 組織レベルのサービス アカウントにプロジェクトへのアクセス権を付与するには、「 既存の組織のアクセス権をプロジェクトに割り当て」を参照してください。 |
各 <span tabindex=\" \" class=\" \">API キーは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトに <span tabindex=\" \" class=\" \">API キーによるアクセスを許可できます。 | 各サービス アカウントは 1 つの組織にのみ属しますが、その組織内の任意の数のプロジェクトへのアクセスをサービスアカウントに許可できます。 |
APIキーを使用して Atlas UI 経由で Atlas にログインすることはできません。 | サービス アカウントまたはそのアクセス トークンを使用して、 Atlas UIから Atlas にログすることはできません。 |
オプション: Atlas Administration API の IP アクセス リストを要求する
Atlas は、 IP アクセス リストが必要な場合を除き、インターネット上の任意のアドレスから Atlas Administration APIリクエストを行うことができます。これにより、 IP アクセスIP アクセス リストで指定されたロケーション ベースのIPまたは CIDR アドレスからの API リクエストのみにAPIリクエストを制限します。
各認証方法には、独自のIP アクセス リストがあります。すべての Atlas Administration APIリクエストにIP アクセス リストが必要な場合は、 APIリクエストを行う前に、 APIキーまたはサービス アカウントに対して少なくとも 1 つのIP アクセス リストのエントリを定義する必要があります。
Atlas UI を使用して組織を作成すると、Atlas ではデフォルトで API アクセス リストの要求が有効になります。を無効にするには、組織を作成する Require IP Access List for the Atlas Administration APIときに、OFF を に切り替えます。
組織の作成後、すべての Atlas Administration API 要求に対して IP アクセス リストを要求するように組織を設定するには、次の手順を実行します。
Atlas で、Organization Settings ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
[Organizations] メニューの横にある [Organization Settings] アイコンをクリックします。
[ Organization Settings ]ページが表示されます。
組織へのプログラムによるアクセスの付与
APIキーまたはサービスアカウントを使用して、組織へのプログラムによるアクセスを許可するには、次の手順に従います。これら2つの認証方法の詳細については、「Atlas 管理API認証」を参照してください。
重要
サービス アカウントは現在プレビュー段階です。 詳細については、「 サービス アカウントの概要 」を参照してください。
必要なアクセス権
次のアクションを実行するには、Atlas に対する Organization Owner アクセス権が必要です。
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 ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
API Key Informationを入力します。
Descriptionと入力します。
Organization Permissions メニューで、API キーの新しいロールを選択します。
をコピーして保存してください。<a class=\" \" href=\" \" title=\" \"><svg xmlns=\" \" width=\" \" height=\" \" fill=\" \" viewbox=\" \" class=\" \" role=\" \" aria-label=\" \"><path fill=\" \" d=\" \"> <path fill=\" \" d=\"Private Key \">
秘密キーは、API リクエストを行う際にパスワードとして機能します。
警告
公開キーと秘密キーのコピーと保存
Private Key は このページに 1 回だけ表示されます。[Copy] ボタンをクリックして、秘密キーをクリップボードに追加します。公開キーと秘密キーの両方を安全に保存します。
Atlas で、Organization Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
サービス アカウント情報を入力します。
Nameと入力します。
Descriptionと入力します。
Client Secret Expiration メニューから期間を選択します。
[ Organization Permissions ] メニューから、サービス アカウントの 新しいロール を選択します。
をコピーして保存してください。<a class=\" \" href=\" \" title=\" \"><svg xmlns=\" \" width=\" \" height=\" \" fill=\" \" viewbox=\" \" class=\" \" role=\" \" aria-label=\" \"><path fill=\" \" d=\" \"> <path fill=\" \" d=\"Client Secret \">
クライアント シークレットは、アクセス トークンを作成するときにパスワードとして機能します。
警告
クライアントの秘密をすべて見ることができるのはこの時だけです。Copy をクリックして、安全な場所に保存します。それ以外の場合は、新しいクライアントシークレットを生成する必要があります。
Atlas 管理 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キーまたはサービスアカウントのいずれかを使用して、プロジェクトへのプログラムによるアクセスを許可するには、次の手順に従います。これら 2 つの認証方法の詳細については、 Atlas 管理 API 認証 を参照してください。
重要
サービス アカウントは現在プレビュー段階です。 詳細については、「 サービス アカウントの概要 」を参照してください。
必要なアクセス権
APIキーにプロジェクトへのアクセス権を付与するには、そのプロジェクトに対するProject Ownerアクセス権が必要です。
プロジェクト へのサービス アカウント アクセスを付与するには、プロジェクトを所有する組織へのOrganization Owner アクセス権が必要プロジェクト。
プロジェクトへの既存の組織のアクセス権の割り当て
組織のAPIキーまたはサービスアカウントをすでに作成している場合は、それらをプロジェクトに割り当てて、そのプロジェクトにAtlas管理APIへのアクセス権を付与できます。
Atlas CLI を使用してプロジェクトに API キーを割り当てるには、次のコマンドを実行します。
atlas projects apiKeys assign <ID> [options]
コマンド構文とパラメーターの詳細については、Atlas CLIドキュメントの「atlas projects apiKeys assign」を参照してください。
Atlas UIを使用して組織APIキーをプロジェクトに割り当てるには、次のようにします。
Atlas で、Project Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API キーをプロジェクトに追加します。
フィールドに公開キーを入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
警告
組織サービス アカウントをプロジェクトに割り当てると、 はシークレットのローテーションやIP アクセス リストの更新など、サービスProject Owner アカウントを管理できます。
Atlas で、Project Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
プロジェクト ロールをサービス アカウントに割り当てます。
表示されるメニューで、サービスアカウントの 1 つまたは複数の新しいロールを選択します。
Atlas 管理 API を使用して、既存のサービス アカウントにプロジェクトへのアクセス権を付与できます。
プロジェクトからのプロジェクトアクセスの追加
組織の API キーまたはサービスアカウントをまだ作成していない場合は、プロジェクトの キー またはサービスアカウントを作成して、そのプロジェクトに Atlas Administration API へのアクセス権を付与できます。 プロジェクトに対して作成したAPIキーまたはサービス アカウントは、権限Organization Member を持つ親組織に自動的に追加されます。
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 ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API Key Informationを入力します。
[Create API Key] ページで次を行います。
Descriptionと入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
をコピーして保存してください。<a class=\" \" href=\" \" title=\" \"><svg xmlns=\" \" width=\" \" height=\" \" fill=\" \" viewbox=\" \" class=\" \" role=\" \" aria-label=\" \"><path fill=\" \" d=\" \"> <path fill=\" \" d=\"Private Key \">
秘密キーは、API リクエストを行う際にパスワードとして機能します。
警告
秘密キーの保存
Private Key は このページに 1 回だけ表示されます。[Copy] ボタンをクリックして、秘密キーをクリップボードに追加します。公開キーと秘密キーの両方を安全に保存します。
Atlas UIを使用してプロジェクトのサービス アカウントを作成する場合
Atlas で、Project Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
サービス アカウント情報を入力します。
Nameと入力します。
Descriptionと入力します。
Client Secret Expiration メニューから期間を選択します。
[Project Permissions（プロジェクト権限）] メニューから、サービス アカウントの 新しいロール を選択します。
をコピーして保存してください。<a class=\" \" href=\" \" title=\" \"><svg xmlns=\" \" width=\" \" height=\" \" fill=\" \" viewbox=\" \" class=\" \" role=\" \" aria-label=\" \"><path fill=\" \" d=\" \"> <path fill=\" \" d=\"Client Secret \">
クライアント シークレットは、アクセス トークンを作成するときにパスワードとして機能します。
警告
クライアントの秘密をすべて見ることができるのはこの時だけです。Copy をクリックして、安全な場所に保存します。それ以外の場合は、新しいクライアントシークレットを生成する必要があります。
Atlas 管理 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 リクエストを行う
アトラス管理APIは、APIキーまたはサービスアカウントという2つの認証方法のいずれかを使用してリクエストを認証します。 次の手順を完了するには、希望認証方法を構成するときに保存したキーまたはシークレットが必要です。
重要
サービス アカウントは現在プレビュー段階です。 詳細については、「 サービス アカウントの概要 」を参照してください。
すべての Atlas Administration API エンドポイントには次のベース URL があります。
https://cloud.mongodb.com/api/atlas/<version>
リクエストは次の例のようになります。ここで、 {PUBLIC-KEY} は API 公開キー、 {PRIVATE-KEY} は対応する秘密キーです。Atlas 管理 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" }'
サービス アカウントを使用して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" }'
あるいは、OpenAPI v3 仕様 をサポートする任意のツールを使用して、コードサンプルやモック サーバーを生成することもできます。たとえば、Atlas Admin API 仕様をPostman にインポートして curl コマンドを生成できます。Postman を使用して curl コマンドを生成するには、次のようにします。
次のステップ
Atlas Administration API の詳細については、「Atlas Administration API リファレンス」を参照してください。
プログラムによる Atlas Administration API へのアクセスを管理するには、次のいずれかの手順を参照してください。