Docs 菜单
Docs 主页
/
MongoDB 阿特拉斯
/
Atlas Device SDKs
/
Kotlin SDK
/
连接到 Atlas

连接到 Atlas App Services - Kotlin SDK

在此页面上

  • 先决条件
  • 初始化应用客户端
  • 默认应用程序客户端
  • 已配置的应用程序客户端
  • 配置应用程序客户端
  • 共享同步连接
  • 配置同步超时
  • 加密应用元数据
  • 设置自定义HTTP headers
  • 启用平台网络
  • 连接到特定MongoDB Server
  • 在运行时连接到不同的MongoDB Server
  • 关闭应用程序客户端

本页介绍如何初始化应用客户端并使用 Kotlin SDK 连接到 Atlas App Services 后端。

应用客户端是 App Services 后端的客户端接口。它允许您与 App Services App 进行交互，并提供对 App Services 功能的访问权限，包括：

每个应用程序客户端都与一个应用程序 ID 相关联。要了解如何在 App Services 用户界面中查找 App ID，请参阅 App Services 文档中的查找 App ID 。

先决条件

在连接到 Atlas App Services 之前，您需要一个带有 App ID 的 App Services App。

要开始使用，请参阅 App Services 文档中的创建应用。

初始化应用客户端

Kotlin SDK 使用App接口访问 App客户端。

每个App客户端都与一个 App ID 相关联。您可以有多个连接到多个应用的应用客户端实例，但共享同一 App ID 的所有应用客户端实例都使用相同的底层连接。

您可以通过调用以下方法之一来初始化应用客户端：

  • .create()：使用默认配置值初始化应用

  • .build()：使用通过AppConfiguration对象传递的自定义配置值初始化应用

初始化应用后，您可以使用App实例访问 App Services 功能。

默认应用程序客户端

要使用默认配置值初始化应用，请将 App Services 应用的 App ID 传递给App.create()方法：

// Creates an App with default configuration values
val app = App.create(YOUR_APP_ID) // Replace with your App ID

已配置的应用程序客户端

AppConfiguration接口允许您使用可选参数配置应用客户端，以便更精细地控制应用连接详细信息，例如自定义请求标头和用于本地加密的密钥。

要控制配置选项，请使用AppConfiguration.Builder并调用.build()方法以传递配置对象：

// Creates an App with custom configuration values
AppConfiguration.Builder(YOUR_APP_ID)
    // Specify your custom configuration values
    .appName("my-app-name")
    .appVersion("1.0.0")
    .baseUrl("http://localhost:9090")
    .build()

配置缓存

在版本1.14.0中进行了更改： baseUrl未缓存在AppConfiguration

初始化 App 客户端时，会在内部缓存配置。

尝试在同一进程中关闭并重新打开配置已更改的应用无效。 客户端继续使用缓存的配置。

从 Kotlin SDK 版本1开始。 14 。 0中， baseUrl()不再缓存在AppConfiguration中。这意味着您可以更改baseUrl ，应用客户端将使用更新后的配置。在早期 SDK 版本中，对缓存的应用配置中的baseUrl进行更改无效。

配置应用程序客户端

以下部分介绍如何构建具有特定属性的AppConfiguration客户端。

共享同步连接

注意

适用于 Atlas Device Sync

此配置选项仅适用于使用 Atlas Device Sync 的应用。 有关通过 Kotlin SDK 使用 Device Sync 的更多信息，请参阅将Device Sync 添加到应用 - Kotlin SDK。

版本 1.13.0 中的新增内容。

默认情况下，SDK 会为每个同步 Realm 单独打开与服务器的连接。 在 Kotlin v 1.13.0及更高版本中，您可以启用会话多路复用。 启用后，SDK 会为单个Atlas App Services用户打开的所有同步 Realm 共享与服务器的连接。 跨多个会话共享连接可减少资源占用并提高性能。

默认情况下，多路复用处于禁用状态。 您可以使用.enableSessionMultiplexing()在AppConfiguration上启用它 方法，它接受一个布尔值。

val config = AppConfiguration.Builder(YOUR_APP_ID)
    .enableSessionMultiplexing(true)
    .build()

启用后，当所有会话关闭时，共享连接不会立即关闭。相反，它会在connectionLingerTime内保持打开状态，默认为30秒。您可以通过向AppConfiguration上的SyncTimeoutOptions.connectionLingerTime()传递新值来覆盖此持续时间。

val configCustomLingerTime = AppConfiguration.Builder(YOUR_APP_ID)
    .enableSessionMultiplexing(true)
    .syncTimeouts {
        connectionLingerTime = 10.seconds // Overrides default 30 secs
    }
    .build()

有关更多信息，请参阅本页上的“配置同步超时”部分。

配置同步超时

注意

适用于 Atlas Device Sync

此配置选项仅适用于使用 Atlas Device Sync 的应用。 有关通过 Kotlin SDK 使用 Device Sync 的更多信息，请参阅将Device Sync 添加到应用 - Kotlin SDK。

版本 1.13.0 中的新增内容。

在 Kotlin v 1中。 13 。 0及更高版本，您可以覆盖在 Atlas 后端和客户端应用程序之间同步数据时使用的默认超时设置。

您可以使用.syncTimeups()方法在AppConfiguration上进行各种同步超时设置。传递要覆盖的特定超时属性值。配置的超时适用于应用程序中的所有同步会话。

val config = AppConfiguration.Builder(YOUR_APP_ID)
    .syncTimeouts {
        connectTimeout = 1.minutes
        connectionLingerTime = 15.seconds
        pingKeepalivePeriod = 30.seconds
        pongKeepalivePeriod = 1.minutes
        fastReconnectLimit = 30.seconds
    }
    .build()

有关可用超时属性及其定义的完整列表，请参阅SyncTimeoutOptionsBuilder API 参考。

加密应用元数据

当您连接到 App Services 时，Realm 会在设备上创建额外的元数据文件。有关这些元数据文件的更多信息，请参阅适用于 Kotlin 的 Atlas Device SDK。

您可以对Atlas App Services在客户端设备上存储的元数据进行加密，这与加密同步Realm的方式类似。

要加密应用元数据，请在初始化应用时将加密密钥传递给encryptionKey属性：

val config =
    AppConfiguration.Builder(YOUR_APP_ID)
        // Specify the encryption key
        .encryptionKey(myEncryptionKey)
        .build()

设置自定义HTTP headers

1.11.0 版本中的新增功能。

如果您将 Atlas App Services 或 Device Sync 与设置一起使用，则可能需要设置自定义 HTTP headers。 Kotlin SDK 支持在应用上设置自定义 HTTP headers。这些标头附加到对 App Services App 的每个请求，包括函数调用。

初始化应用时，可以传递：

AppConfiguration.Builder(YOUR_APP_ID)
    .authorizationHeaderName("MyApp-Authorization")
    .customRequestHeaders { put("X-MyApp-Version", "1.0.0") }
    .build()

启用平台网络

1.14.0版本新增。

Atlas Device SDK 的平台网络允许您使用平台的网络堆栈而不是默认的 WebSocket 客户端来处理 Device Sync 流量。

启用后，您可以将在 Android 和 Java 虚拟机 (JVM) 平台上运行的应用程序配置为通过 OkHttp 使用托管 WebSocket 。托管 WebSocket 为需要身份验证的代理和防火墙提供高级配置支持。

默认情况下，平台网络处于禁用状态。您可以使用AppConfiguration.usePlatformNetworking()方法在AppConfiguration上启用它，该方法接受一个布尔值。

val config =
    AppConfiguration.Builder(YOUR_APP_ID)
        .usePlatformNetworking(true)
        .build()

注意

仅限 Android 和 JVM 平台

此功能目前仅适用于 Android 和 Java 虚拟机 (JVM) 平台。

连接到特定MongoDB Server

默认情况下，Atlas Device SDK 使用https://services.cloud.mongodb.com的全局baseUrl连接到 Atlas。 在某些情况下，您可能想要连接到不同的服务器：

您可以在AppConfiguration中指定baseUrl ：

// Specify a baseUrl to connect to instead of the default
val config = AppConfiguration.Builder(YOUR_APP_ID)
    .baseUrl("https://example.com")
    .build()

在运行时连接到不同的MongoDB Server

1.16.0版本新增。

在某些情况下，您可能希望在应用程序运行时更改baseUrl 。例如，您可能希望在边缘服务器之间漫游或从 App Services 连接移动到边缘服务器连接。

要在运行时更改baseUrl ，请调用实验性app.updateBaseUrl方法。 您可以传递null将baseUrl重置为默认值。

// Specify a custom baseUrl to connect to.
// In this case, an Edge Server instance running on the device:
val config = AppConfiguration.Builder(EDGE_SERVER_APP_ID)
    .baseUrl("http://localhost:80")
    .build()
val app = App.create(config)
// ... log in a user and use the app ...
// Later, change the baseUrl.
// In this case, pass `null` to reset to default:
// https://services.cloud.mongodb.com
app.updateBaseUrl(null)

此 API 是实验性的，需要@ExperimentalEdgeServerApi注释：

// Opt in to the experimental Edge Server API
@OptIn(ExperimentalEdgeServerApi::class)

如果您在用户登录并打开同步数据库后更改baseUrl ，则该应用必须执行客户端重置。有关详细信息，请参阅处理客户端重置错误。

在代码中执行以下操作：

  1. 暂停同步会话

  2. 使用app.updateBaseUrl方法更新baseUrl

  3. 对用户重新进行身份验证，以使用新的 baseUrl

  4. 打开同步数据库，从新服务器提取数据

服务器和客户端都必须在线，用户才能进行身份验证并连接到新服务器。如果服务器不在线或客户端没有网络连接，则用户无法进行身份验证并打开数据库。

关闭应用程序客户端

您可以使用App.close()方法手动关闭应用实例并释放所有底层资源：

app.close()

如果未手动关闭，则在对 App 实例进行垃圾收集时会释放资源。

后退

连接到 Atlas

来年

调用 Atlas Function

在此页面上