連接器 (Connector) 資料結構
介紹
什麼是連接器？
連接器 (Connectors) 在 Logto 中扮演關鍵角色。透過它們的幫助，Logto 使終端使用者能夠使用無密碼註冊或登入，以及使用社交帳戶登入的功能。隨著網站和應用程式的普及，無密碼和社交登入讓使用者避免管理大量帳戶和密碼。
如果你想設定現有的連接器，請參閱我們的 連接器指南。如果找不到你想設定的連接器，可以參考 開發你的連接器 中的指南來開發這些連接器。
組成
連接器資料中有許多屬性。
為了提高資料載入和更新的效率，我們將部分頻繁修改的連接器資料存儲到資料庫中，其餘的則本地存儲。
- 本地存儲，也稱為 ConnectorMetadata，是一個包含固定屬性的物件，如 logo、連接器類型等。(:face_with_monocle: 對這些屬性有疑問嗎？不用擔心，稍後會有詳細解釋！)
- 遠端存儲 是存儲在資料庫中，以便對這些資料進行相對頻繁的更改。
連接器的本地存儲：ConnectorMetadata {#connectors-local-storage-connectormetadata}
id
id 是一個 唯一 的字串類型鍵，用於識別 Logto 中的連接器。
它由每個連接器的開發者分配，並將上傳到資料庫。
target (身分提供者名稱)
target 是一個小寫字串，用於區分社交連接器的社交身分來源。
Logto 使用者可以將此變數視為「身分提供者名稱」以便更好理解。
例如，如果你使用 Google 帳戶登入 Logto，則 target 應為 google。target 的值可以是任意非空字串，但我們鼓勵你保持簡單明瞭，因為你無法更改它。我們不允許存在具有相同 target 和平台的多個連接器。另一方面，你可以為不同平台的社交連接器使用相同的 target。例如，如果使用者想在手機上透過 WeChat 登入，根據 WeChat 的使用條款，需要一個原生 WeChat 應用程式；同時，還需要一個網頁 WeChat 應用程式來啟用網頁應用程式的登入。這兩個 WeChat 應用程式共享相同的身分提供者，應具有相同的 target。
由於 target 是一個複雜的概念，我們總結了不同的使用案例和建議。
| 範例 | 情境 | 結果 | 推薦？ | |
|---|---|---|---|---|
| 不同 IdP 和不同 targets | 1. GitHub 連接器 (target: github) 2. Google 連接器 (target: google) | 支援使用 GitHub 和 Google 帳戶登入的應用程式。 | 最常見的使用案例。 | ✅ |
| 不同 IdP 和相同 target | 1. GitHub 連接器 (target: github) 2. Google 連接器 (target: github) | 不適用 | 使用者可能會使用另一個使用者的 GitHub 帳戶登入到 Logto 帳戶。 | ❌ |
| 相同 IdP 和不同 targets | 1. GitHub 連接器 (target: github) 2. OAuth GitHub 連接器 (target: github_oauth) | GitHub 連接器用於應用程式 A，而 OAuth GitHub 連接器專為應用程式 B 創建。 | 使用這兩個不同的連接器登入 Logto 時，將始終創建不同的 Logto 帳戶，即使使用者使用相同的 GitHub 帳戶。 | 分割使用者池是唯一需要使用兩個連接器的情境。然而，通常認為最佳做法是創建兩個單獨的租戶來處理此使用案例。 |
| 相同 IdP 和相同 target | 1. GitHub 連接器 (target: github) 2. OAuth GitHub 連接器 (target: github) | 不適用 | 使用這兩個連接器中的任何一個都可以得到完全相同的結果。 | 創建兩個基本上做同樣事情的連接器可能會讓終端使用者感到困惑，並且沒有多大意義。最好使用一個適合你特定使用案例的連接器。 |
type
type 是記錄連接器類型的屬性。
我們根據功能將連接器分為三種類型：
- Social：可以在終端使用者授權下從任意第三方社交媒體存取使用者資訊的連接器。
- SMS：使終端使用者能夠在手機上接收簡訊的連接器。
- Email：可以幫助向終端使用者發送電子郵件的連接器。
platform
platform 用於識別連接器是為哪個平台構建的。
platform 應為 null 或以下字串類型值之一：
- Native：僅適用於原生行動應用程式的連接器。
- Web：僅適用於桌面網頁應用程式的連接器。
- Universal：可以在行動網頁應用程式和桌面網頁應用程式上運行的連接器。
email 連接器 和 SMS 連接器 的 platform 應始終為 null。
僅 social 連接器 可以有非 NULL 的 platform 值。
name
name 是一個物件，其鍵是 i18n 國家代碼，值是連接器的顯示名稱。
description
description 也是一個物件，其鍵是 i18n 國家代碼，值是連接器的簡要描述。
為了在客戶端支援 i18n 顯示，我們將 name（以及 description）屬性存儲為一個映射，使用國家代碼作為鍵，當地字符的名稱（或描述）作為值。
logo
logo 是連接器 logo 的 URL 或相對路徑。
logoDark
logoDark 是連接器深色模式 logo 的 nullable URL 或相對路徑。
logo 是必需的，而 logoDark 是可選的。
我們在淺色模式下顯示 logo，如果存在 logoDark，則在深色模式下顯示 logoDark。否則將回退顯示 logo 在深色模式下。
isStandard
isStandard 是一個可選的布林屬性，用於識別社交連接器是否為「標準」連接器。你可以透過其真值 isStandard 屬性識別「標準」連接器。
Logto 僅支援「標準」社交連接器。也就是說，所有 Logto 的 Email 或 SMS 連接器都不是「標準」。
Logto 將基於開放和標準協議（例如 OAuth、OIDC、SAML 等）構建的連接器稱為「標準」連接器。Logto 的使用者預期在每個標準連接器上構建多個實例。例如，假設 Logto 已經提供了一個 OAuth 標準連接器，使用者可以構建「OAuth GitHub 連接器」、「OAuth Google 連接器」和「OAuth Facebook 連接器」實例。它們都基於 Logto OAuth 標準連接器。
如果你熟悉 Logto 的連接器設計，最多只能同時存在一個 Email 或 SMS 連接器，這意味著 Logto 目前階段不需要「標準」的 Email 或 SMS 連接器。
readme
readme 是連接器 README markdown 文件的相對路徑，其內容將在連接器設置過程中顯示於「管理控制台」。
configTemplate
configTemplate 是連接器配置範例的相對路徑。
連接器的遠端存儲：Connector DB {#connectors-remote-storage-connector-db}
id
id 作為連接器資料庫的主鍵，是一個隨機生成的字串類型鍵，用於識別資料庫中的連接器。
connectorId
connectorId 是一個字串類型鍵，是連接器資料庫和 ConnectorMetadata 對齊的唯一橋樑。對於每個匹配的連接器資料庫資料和連接器代碼模組對，connectorId 始終等於代碼模組的 metadata.id。
metadata
metadata 是 ConnectorMetadata 的子集，包含可配置的屬性，即 logo、logoDark、target 和 name。
syncProfile
syncProfile 是一個布林值，用於確定使用者資料更新方案，默認為 FALSE。
如果 syncProfile 為 FALSE，Logto 使用者的基本資訊（包括名稱和頭像）將僅在使用者首次透過此連接器註冊到 Logto 時更新。否則，每次使用者透過連接器登入 Logto 時，Logto 帳戶資料將被更新。
config
config 可以是任意非空物件。
這是連接器存儲其配置的地方。每個連接器在 config 中有不同的屬性，並且在保存到資料庫之前必須有效（連接器對「有效」有不同的標準）。只有通過有效性檢查的 config 才能更新到資料庫，否則會拋出錯誤。
開發者在開發自己的連接器時需要實現 config 保護，詳情請參閱 開發你的連接器。
想要查看 config 範例嗎？請訪問 連接器 或每個連接器的設置頁面。
在當前的 Logto 版本中，同一時間只能存在一個 Email/SMS 連接器，所有其他具有相同類型的連接器將自動刪除。
唯一工作的 Email 或 SMS 連接器的規則不適用於 Social 連接器。
換句話說，你可以添加多個 Social 連接器。
createdAt
createdAt 是一個自動生成的時間戳字串，用於追蹤連接器在資料庫中創建的時間。