MongoDB 連線 URI 簡介

簡介

連線到您的資料庫伺服器通常是設計和設定資料庫支援應用程式時需要完成的首要任務之一。雖然有很多種方法可以向應用程式提供位址、監聽埠、憑證和其他詳細資訊，但連線 URI（有時稱為連線字串或連線 URL）是以精簡格式指定複雜組態最強大且最彈性的方式之一。

在本指南中，我們將討論如何使用您的 MongoDB 資料庫資訊和身份驗證詳細資訊來格式化連線 URI。連線 URI 分為多個部分，因此我們將逐步介紹每個部分。

百分比編碼值

在我們開始之前，我們應該提到 MongoDB 連線 URI 預期百分比編碼值。這表示 URL 中具有特殊含義的任何字元都必須轉換為其百分比編碼的對應字元，以確保程式庫和應用程式可以正確解釋它們。

您應該進行百分比編碼的字元包括

• :: %3A
• /: %2F
• ?: %3F
• #: %23
• [: %5B
• ]: %5D
• @: %40

這些在連線 URI 中具有特殊含義。

所以如果您的密碼是...

pe@ce&lo\/3

...您會想要在連線 URI 中將其指定為

pe%40ce&lo\%2F3

如果您不確定字元是否應該進行百分比編碼，通常最好還是進行編碼。例如，如果您不確定 \ 字元是否為保留字元，您可以使用其百分比編碼的等效字元 %5C，以確保安全

pe%40ce%26lo%5C%2F3

在您建立連線 URI 時，請記住這一點。

快速概覽

在我們深入細節之前，我們可以先看看 MongoDB 連線 URI 的規格

mongodb://[username:password@]host[:port][,...hostN[:port]][/[database][?parameter_list]]

\________/\__________________/\___________________________/\__________/\________________/
     |             |                        |                    |             |
     |- schema     |- auth credentials      |                    |             |- parameter list
                                            |                    |
                                            |                    |- default authentication database
                                            |
                                            |- host specifier

方括號中的部分表示選用部分。您可能已經注意到 URI 的大部分部分都是選用的。也可能很明顯，您可以在 URI 中編碼許多資訊。

每個個別組件的快速描述

• mongodb://：用於將字串識別為 MongoDB 連線 URI 的結構描述識別符。
• 驗證憑證：URI 的選用組件，可用於指定要連線的使用者和密碼。
  • username：選用的使用者名稱。如果包含，它應該從第二個斜線 (/) 後面開始，並持續到冒號 (:)。如果包含，則必須附帶 password。
  • password：選用的密碼。如果包含，它從冒號 (:) 後面開始，並持續到 at 符號 (@)。如果包含，則必須附帶 username。
• 主機指定符：用於指定要連線的一個或多個主機名稱和埠的必要組件。
  • host：要連線的伺服器的 IP 位址、DNS 名稱或本機可解析名稱。主機名稱持續到冒號 (:)（如果包含埠號）、逗號 (,)（如果指定多個主機），否則持續到斜線 (/)。必須提供至少一個主機。
  • port：選用的埠號規格，用於指示 MongoDB 在主機上監聽的埠。埠號以冒號 (:) 開頭，並持續到逗號 (,)（如果提供另一個主機）或斜線 (/)（如果沒有）。
• 預設身份驗證資料庫：如果參數列表中未提供更具體的 authSource，則要驗證身份的資料庫名稱。如果此處或 authSource 中未指定資料庫，MongoDB 將嘗試驗證到標準 admin 資料庫。
• 參數列表：可用於影響連線行為的額外參數的選用列表。參數列表以問號 (?) 開頭。如果未提供預設身份驗證資料庫，您必須在最後一個主機定義之後，以斜線和問號 (/?) 開始參數列表。
  • 參數對：參數列表由鍵值對組成。每個對中的鍵和值以等號 (=) 分隔，並且每對之間以 & 符號 (&) 分隔。

以下是包含所有這些組件的 MongoDB 連線 URI 範例

mongodb://sally:sallyspassword@dbserver.example:5555/userdata?tls=true&connectionTimeout=5000
 ^          ^         ^               ^           ^     ^          ^
 |- schema  |         |- password     |- host     |     |          |- parameter list
            |                                     |     |
            |- username                           |     |- default authentication database
                                                  |
                                                  |- port

指定 URI 類型

連線 URI 中的項目通常是協定規格或應用程式類型。由於 URI 將用於連線和驗證到 MongoDB 資料庫，因此我們需要使用一個標識符來向我們正在使用的應用程式和程式庫表明這一點。

MongoDB 專案僅接受 mongodb 作為有效的 URI 結構描述指示符。因此，您應始終像這樣啟動您的連線 URI

mongodb://

結構描述指示符將確保後續的資訊在正確的上下文中被解釋。

指定使用者名稱和密碼

URI 的下一個部分是使用者憑證。使用者憑證是選用的，但如果您不想依賴您的應用程式或資料庫設定的預設值，則通常是必要的。

要包含使用者憑證，請在結構描述識別符後提供使用者名稱，後跟冒號 (:)、密碼，最後是 at 符號 (@)

mongodb://username:password@

使用者憑證是選用的，但如果包含，您必須同時提供使用者名稱和密碼組件。

指定伺服器監聽位置

使用者憑證之後是主機指定符，它定義伺服器的監聽位置。可以在主機指定符中定義一個或多個主機，但由於主機指定符是必要的，因此必須至少提供一個主機。

每個主機定義都包含一個 host 和一個選用的 port。host 可以是本機可解析的主機名稱、由外部名稱系統（如 DNS）解析的名稱，或 IP 位址或其他直接位址。埠號表示 MongoDB 在主機上監聽的埠號。

若要指定應用程式應嘗試連線到本機電腦上的預設 MongoDB 埠 (27017)，您可以使用

mongodb://127.0.0.1

如果您需要包含使用者名稱和密碼，則該資訊將會放在前面，並以 at 符號分隔

mongodb://username:password@localhost

若要指定在非標準埠上執行的遠端伺服器，請使用冒號分隔這些詳細資訊。例如，若要連線到位於 198.51.100.22 的主機上的埠 3333，您可以使用

mongodb://username:password@198.51.100.22:3333

若要定義多個主機和埠對，請用逗號 (,) 分隔這些集合，以告知應用程式在無法連線到第一個伺服器時嘗試後面的伺服器。例如，若要擴展先前的範例以包含在 198.51.100.33 上埠 5555 監聽的備用伺服器，您可以使用

mongodb://username:password@198.51.100.22:3333,198.51.100.33:5555

符合規範的用戶端和應用程式將嘗試首先連線到在 198.51.100.22:3333 監聽的伺服器。如果失敗，它們將嘗試連線到在 198.51.100.33:5555 監聽的 MongoDB 資料庫。

提供預設身份驗證資料庫

在主機指定符之後，下一個資料片段是預設身份驗證資料庫。雖然並非所有資料庫管理系統都是如此，但在 MongoDB 中，您必須在建立連線時針對特定資料庫進行身份驗證。

資料庫名稱以正斜線 (/) 開頭，並持續到行尾或問號 (?)。如果參數列表中未提供 authSource 選項，則將使用預設身份驗證資料庫。如果兩者都未提供，用戶端將針對 admin 資料庫進行身份驗證。

若要連線到託管在 198.51.100.22:3333 上監聽的 MongoDB 伺服器上的名為 sales 的資料庫，您可以輸入

mongodb://username:password@198.51.100.22:3333/sales

指定額外參數

連線 URI 的最後一部分用於為連線提供額外參數。參數列表以開頭問號 (?) 引入，並持續到行尾。如果未提供預設身份驗證資料庫，則指示主機規格結尾的尾隨斜線必須直接位於問號 (/?) 之前。

列出的每個參數都定義為以等號 (=) 連接的鍵值對。在第一個參數對之後，每個額外的鍵值對都以 & 符號 (&) 分隔。

例如，若要指定用戶端應為我們先前定義的連線應用 10 秒逾時，您可以使用

mongodb://username:password@198.51.100.22:3333/sales?connectTimeoutMS=10000

如果您想提供額外參數，您可以在之後添加它們，並在每對之間使用 & 符號 (&)。例如，我們可以另外指定我們需要 SSL，並且指定的主機是我們想要連線的複本集的成員

mongodb://username:password@198.51.100.22:3333,198.51.100.33:5555/sales?connectTimeoutMS=10000&tls=true&replicaSet=someReplicaSet

MongoDB 文件有一個完整參數列表，您可以閱讀以了解更多資訊。

結論

在本指南中，我們討論了什麼是 MongoDB 連線 URI、如何解釋各種組件，以及如何在給定一組連線資訊的情況下建構您自己的 URI。連線 URI 將連線到給定資料庫所需的所有資訊編碼在單個字串中。由於這種彈性以及它們的廣泛採用，了解如何解析和建構這些字串可能會非常有幫助。