Stable API

이 페이지의 내용

Stable API란 무엇이며 이를 사용해야 하나요?

이전 버전과의 호환성 보장
API 버전 선언
클라이언트 API 버전 확인
엄격한 클라이언트 생성
Stable API 명령으로 마이그레이션
Stable API 외부에서 명령어 및 기능을 사용하는 방법
Stable API 명령
매개변수
행동
Stable API 오류 응답

Stable API란 무엇이며 이를 사용해야 하나요?

MongoDB Stable API(이전에는 Versioned API로 표시됨)를 사용하면 원하는 대로 MongoDB 서버를 업그레이드할 수 있으며, MongoDB 버전 간의 동작 변경으로 인해 애플리케이션이 중단되지 않도록 할 수 있습니다.

MongoDB 5.0에는 MongoDB 서버 제품과 통신하는 애플리케이션을 위한 Stable API가 도입되었습니다. Stable API를 사용하면 애플리케이션이 실행되는 MongoDB API 버전을 지정할 수 있습니다.

Stable API는 애플리케이션에 장기적인 API 안정성을 제공하며, 더 잦은 출시와 자동 서버 업그레이드를 지원합니다. 이를 통해 애플리케이션은 이전 버전과의 호환성이 손상되는 변경에 관한 위험 없이 빠르게 출시된 기능을 활용할 수 있습니다.

드라이버 연결의 기본 동작은 명시적으로 apiVersion을 지정하지 않더라도 예상대로 계속 작동합니다.

Stable API는 애플리케이션이 데이터를 읽고 쓰고, 컬렉션과 인덱스를 만들고, 기타 일반적인 작업을 수행하는 데 사용하는 MongoDB 명령 하위 집합을 포함합니다.

참고

2022년 2월부터 " 버전이 지정된 API " 용어가 " Stable API " 로 변경되었습니다. 이름은 변경되나 모든 개념과 기능은 동일하게 유지됩니다.

이전 버전과의 호환성 보장

서버 업그레이드로 인해 애플리케이션에서 중요한 동작 변경이 발생하지 않습니다. 이러한 보장은 새 서버가 지정된 API 버전을 지원하는 한 유지됩니다.

이전 버전과의 호환성을 보장하려면 애플리케이션이 반드시 다음과 같아야 합니다.

API 버전 선언
지정된 API 버전에서 지원되는 명령 및 기능만 사용
지원되는 공식 드라이버 버전으로 배포

API 버전 선언

➤ 오른쪽 상단의 언어 선택 드롭다운 메뉴를 사용하여 이 페이지에 있는 예시의 언어를 설정하세요.

Stable API를 사용하려면 최신 드라이버로 업그레이드하고 애플리케이션의 MongoClient를 생성합니다.

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")};
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIExample is an example of creating a client with stable API.
func StableAPIExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .build()
                ).build()
        );
return client;

    from pymongo.server_api import ServerApi
    client = AsyncIOMotorClient(uri, server_api=ServerApi("1"))

client = new MongoClient(uri, { serverApi: { version: '1' } });

$serverApi = new \MongoDB\Driver\ServerApi('1');
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

from pymongo.server_api import ServerApi
MongoClient(uri, server_api=ServerApi("1"))

client = Mongo::Client.new(uri_string, server_api: {version: "1"})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, options: opts)

"1" 이 현재 사용 가능한 유일한 API 버전입니다.

기본적으로 클라이언트는 엄격하지 않습니다. 엄격하지 않은 클라이언트를 사용하면 Stable API에 속하는지 여부에 관계없이 모든 명령을 실행할 수 있습니다.

클라이언트 API 버전 확인

serverStatus 명령을 사용하여 애플리케이션의 구성된 API 버전을 확인합니다. MongoDB 인스턴스에 연결된 각 애플리케이션에 대해 appname이 apiVersions 문서에 나타납니다.

자세한 내용은 metrics.apiVersions를 참조하세요.

db.runCommand( { serverStatus: 1 } ).metrics.apiVersions

엄격한 클라이언트 생성

엄격한 클라이언트는 Stable API 외부의 모든 명령을 거부합니다. Stable API 외부에서 명령을 사용하려고 하면 APIVersionError 응답을 받게 됩니다.

엄격한 클라이언트는 쿼리 계획 및 실행 중에 지원되지 않는 인덱스 유형도 무시합니다.

샘플 코드를 사용하여 엄격한 클라이언트를 생성합니다.

mongosh --apiVersion 1 --apiStrict

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, true);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(true);  // Enable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: true);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIStrictExample is an example of creating a client with strict stable API.
func StableAPIStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(true)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(true)
                .build()
                ).build()
        );
return client;

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=True))

client = new MongoClient(uri, { serverApi: { version: '1', strict: true } });

$serverApi = new \MongoDB\Driver\ServerApi('1', true);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=True))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: true})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(true)
    .build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, options: opts)

Stable API 명령으로 마이그레이션

애플리케이션을 Stable API를 사용하도록 마이그레이션하려면 다음을 수행해야 합니다.

새로운 MongoClient 옵션으로 애플리케이션의 테스트 모음을 실행하세요.
Stable API 외부에서 사용 중인 명령과 기능을 확인합니다.
Stable API의 대체 명령 및 기능으로 마이그레이션하세요.

애플리케이션이 Stable API에 정의된 명령어와 기능만 사용한다면, 새로운 MongoClient 옵션으로 애플리케이션을 재배포할 수 있으며, 향후 서버 업그레이드가 애플리케이션에 부정적인 영향을 미치지 않을 것이라고 확신할 수 있습니다.

Stable API 외부에서 명령어 및 기능을 사용하는 방법

Stable API 외부의 명령과 기능을 사용하려면 엄격하지 않은 클라이언트를 사용하여 배포서버에 연결할 수 있습니다. 기본적으로 클라이언트는 엄격하지 않습니다.

엄격하지 않은 클라이언트를 생성하려면 다음 샘플 코드를 사용하세요.

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, false);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(false);  // Explicitly disable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: false);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPINonStrictExample is an example of creating a client with non-strict stable API.
func StableAPINonStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(false)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(false)
                .build()
                ).build()
        );

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=False))

client = new MongoClient(uri, { serverApi: { version: '1', strict: false } });

$serverApi = new \MongoDB\Driver\ServerApi('1', false);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=False))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: false})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(false)
    .build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, options: opts)

이 엄격하지 않은 클라이언트를 사용하면 Stable API 외부에서 명령을 실행할 수 있습니다. 예를 들어, 이 엄격하지 않은 클라이언트를 사용하면 createUser 명령을 실행할 수 있습니다.

중요

Stable API 외부의 명령과 기능은 버전이 지정된 대안과 동일한 이전 버전과의 호환성을 보장하지 않습니다.

Stable API 명령

Stable API V1에 포함된 데이터베이스 명령은 사용 중인 MongoDB 버전에 따라 다릅니다. Stable API에 포함된 데이터베이스 명령과 해당 명령이 도입된 MongoDB 버전을 확인하려면 Stable API 변경 로그를 참조하세요.

매개변수

애플리케이션의 MongoDB 드라이버 연결 코드에서 Stable API에 대해 다음과 같은 선택적 매개 변수를 지정할 수 있습니다. 자세한 내용은 애플리케이션에서 사용하는 드라이버의 MongoDB 드라이버 설명서를 참조하세요.

Parameter	유형	설명
apiVersion	문자열	API 버전을 지정합니다. `"1"`이(가) 현재 지원되는 유일한 버전입니다.
apiStrict	부울	`true`인 경우: 선언된 API 버전에 포함되지 않은 명령을 사용하면 APIStrictError 오류가 반환됩니다. Stable API 에서 지원하지 않는 인덱스는 쿼리 플래너에서 무시됩니다. apiStrict를 지정하는 경우 apiVersion도 지정해야 합니다. 지정하지 않으면 기본값은 `false`입니다.
apiDeprecationErrors	부울	`true`인 경우, 지정된 API 버전에서 더 이상 사용되지 않는 명령이나 동작을 사용하면 APIDeprecationError가 반환됩니다. apiDeprecationErrors를 지정하는 경우, apiVersion도 지정해야 합니다. 지정하지 않으면 기본값은 `false`입니다.

행동

Parameter Validation

MongoDB 5.0부터 API V1 데이터베이스 명령은 명시적으로 허용하지 않는 매개 변수를 전달하면 오류가 발생합니다.

Stable API 오류 응답

이 표에는 문제가 있는 Stable API 요청에 대한 오류 응답이 제시되어 있습니다.

서버 응답	요청
APIDeprecationError	API 버전 `V`에서 `{ apiDeprecationErrors: true }`를 지정하고 `V`에서 더 이상 사용되지 않는 동작을 사용합니다.
APIStrictError	API 버전 `V`로 `{ apiStrict: true }`를 지정하지만, 버전 `V`에 없는 동작을 사용합니다.
APIVersionError	서버가 지원하지 않는 apiVersion을 지정합니다.
InvalidOptions	`{ apiStrict: true }` 또는 `{ apiDeprecationErrors: true }`를 지정하되 apiVersion은 생략합니다.

돌아가기

서버 세션

최신 버전으로 마이그레이션