MySQL :: MySQL Shell 8.4 :: 6.9 標記中繼資料

版本 8.4

9.0
8.0

8.0 日文

MySQL Shell 8.4 / MySQL AdminAPI / 標記中繼資料

6.9 標記中繼資料

可設定的標記架構可用於標記 InnoDB Cluster、InnoDB ClusterSet 或 InnoDB ReplicaSet 的中繼資料，並提供額外資訊。標記可將自訂的鍵值對關聯至叢集、ReplicaSet 或執行個體。標記已保留給 MySQL Router 使用，以便相容的 MySQL Router 支援對應用程式隱藏執行個體。下列標記已保留用於此用途

_hidden 指示 MySQL Router：將執行個體從用戶端應用程式的可能目的地清單中排除。
_disconnect_existing_sessions_when_hidden：指示路由器中斷與標記為隱藏的執行個體的現有連線。

如需更多資訊，請參閱將執行個體從路由中移除。

此外，標記架構是使用者可設定的。自訂標記可以包含任何 ASCII 字元並提供 命名空間，作為可以與叢集、ReplicaSet 或其特定執行個體關聯的字典鍵值對。標記值可以是任何 JSON 值。此設定可讓您在頂層的中繼資料上新增您自己的屬性。

顯示標記

Cluster.options() 操作會顯示指派給個別叢集執行個體以及叢集本身之標記的相關資訊。例如，指派給 myCluster 的 InnoDB Cluster 可能會顯示

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": false
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

此叢集具有名為 location 的全域標記，其值為 US East，並且已標記執行個體 ic-1。

設定叢集執行個體上的標記

您可以在執行個體層級設定標記，例如，您可以將執行個體標記為不可用，以便應用程式和路由器將其視為離線。使用 Cluster.setInstanceOption(instance, option, value) 操作來設定執行個體的標記值。

instance 引數是目標執行個體的連線字串。option 引數必須是字串，格式為 namespace:option。value 參數是應指派給指定 命名空間中 option 的值。如果值是 null，則會從指定的 命名空間移除 option。對於屬於叢集的執行個體，setInstanceOption() 操作只接受 tag 命名空間。任何其他命名空間都會導致 ArgumentError。

例如，若要使用 JavaScript 將標記 test 設定為 true 在 myCluster 執行個體 ic-1 上，請發出

mysql-js> myCluster.setInstanceOption("icadmin@ic-1:3306", "tag:test", true);

或者，使用 Python 將標記 test 設定為 true 在 myCluster 執行個體 ic-1 上，請發出

mysql-py> myCluster.set_instance_option("icadmin@ic-1:3306", "tag:test", True);

將執行個體從路由中移除

當 AdminAPI 和 MySQL Router 一起運作時，它們支援特定標記，讓您可以將執行個體標記為隱藏並將其從路由中移除。然後，MySQL Router 會將此類標記的執行個體從路由目的地候選清單中排除。此功能可讓您安全地將伺服器執行個體離線，以便應用程式和 MySQL Router 忽略它。例如，當您執行維護工作 (例如伺服器升級或組態變更) 時。

當 _hidden 標記設定為 true 時，這會指示 MySQL Router 將執行個體從用戶端應用程式的可能目的地清單中排除。執行個體仍然在線上，但不會路由到新傳入的連線。_disconnect_existing_sessions_when_hidden 標記會控制如何關閉與執行個體的現有連線。此標記假設為 true，並指示任何針對 InnoDB Cluster、InnoDB ClusterSet 或 InnoDB ReplicaSet 引導啟動的 MySQL Router 執行個體中斷與執行個體的任何現有連線，當 _hidden 標記為 true 時。

當 _disconnect_existing_sessions_when_hidden 為 false 時，如果 _hidden 為 true，則不會關閉任何與執行個體的現有用戶端連線。保留的 _hidden 和 _disconnect_existing_sessions_when_hidden 標記專屬於執行個體，且無法在叢集層級使用。

警告

當啟用 use_gr_notifications MySQL Router 選項時，其預設值為 60 秒。這表示當您設定標記時，MySQL Router 最多需要 60 秒才能偵測到變更。若要減少等待時間，請將 use_gr_notifications 變更為較低的值。

例如，假設您想要從路由目的地中移除屬於指派給 myCluster 的 InnoDB Cluster 一部分的 ic-1 執行個體。使用 setInstanceOption() JavaScript 操作來啟用 _hidden 和 _disconnect_existing_sessions_when_hidden 標記

mysql-js> myCluster.setInstanceOption("icadmin@ic-1:3306", "tag:_hidden", true);

或者，使用 set_instance_option() Python 操作來啟用 _hidden 和 _disconnect_existing_sessions_when_hidden 標記

			mysql-js> myCluster.set_instance_option("icadmin@ic-1:3306", "tag:_hidden", true);

您可以藉由檢查選項來驗證中繼資料中的變更。例如，對 ic-1 所做的變更會顯示在選項中，如下所示

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": true
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": []
        }
    }
}

您可以藉由檢視記錄檔來驗證 MySQL Router 是否已偵測到中繼資料中的變更。偵測到對 ic-1 所做的變更的 MySQL Router 會顯示類似如下的變更

2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700] Potential changes detected in cluster 'testCluster' after metadata refresh
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700] view_id = 4, (3 members)
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RW
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RO
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RO hidden=yes disconnect_when_hidden=yes
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_x_ro listening on 64470 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_x_rw listening on 64460 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_rw listening on 6446 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_ro listening on 6447 got request to disconnect invalid connections: metadata change

若要將執行個體重新連線，請使用 setInstanceOption() 操作來移除標記，而 MySQL Router 會自動將執行個體重新新增至路由目的地，而且它會針對應用程式變成線上。例如

mysql-js> myCluster.setInstanceOption(icadmin@ic-1:3306, "tag:_hidden", false);

再次檢查選項來驗證中繼資料中的變更

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": false
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": []
        }
    }
}

您也可以使用下列命令的輸出中的屬性 hiddenFromRouter 來檢視成員上的 _hidden 狀態

Cluster.status()
Cluster.describe()
ReplicaSet.status()

此屬性對於使用 _hidden 中繼資料標記從 MySQL Router 流量隱藏的任何成員都是 true。

設定叢集上的標記

Cluster.setOption(option, value) 操作可讓您變更整個叢集的命名空間選項值。option 引數必須是字串，格式為 namespace:option。

value 參數是要指派給指定 命名空間中 option 的值。如果值是 null，則會從指定的 命名空間移除 option。對於叢集，setOption() 操作接受 tag 命名空間。任何其他命名空間都會導致 ArgumentError。

提示

在叢集層級設定的標記不會覆寫在執行個體層級設定的標記。您無法使用 Cluster.setOption() 來移除在執行個體層級設定的所有標記。

並非所有執行個體都必須在線上，只有叢集具有仲裁即可。若要使用設定為 US East 的 location 標記來標記指派給 myCluster 的 InnoDB Cluster，請在 JavaScript 中發出下列命令

mysql-js> myCluster.setOption("tag:location", "US East")
mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

或者在 Python 中發出下列命令

mysql-py> myCluster.set_option("tag:location", "US East")
mysql-pys> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

從叢集移除標記

若要從叢集移除標記，請使用 Cluster.setOption(option, value) 操作，在 JavaScript 中使用 null 值，在 Python 中使用 None 值。

若要從具有 location 標記的指派給 myCluster 的 InnoDB Cluster 移除標記，請在 JavaScript 中發出下列命令

mysql-js> myCluster.setOption("tag:location", null)

或者使用 Python

mysql-js> myCluster.set_option("tag:location", None)

使用者自定義標籤

AdminAPI 支援 tag 命名空間，您可以在該命名空間中儲存與特定叢集 (Cluster)、複本集 (ReplicaSet) 或執行個體相關聯的鍵值對資訊。 tag 命名空間下的選項不受限制，也就是說，只要是有效的 MySQL ASCII 識別碼，您可以使用任何資訊來標記。

您可以為標籤使用任何名稱和值，只要名稱遵循以下語法：_ 或字母開頭，後面接著字母數字和 _ 字元。

namespace 選項是冒號分隔的字串，格式為 namespace:option，其中 namespace 是命名空間的名稱，而 option 則是實際的選項名稱。您可以在執行個體層級，或者在叢集或複本集層級設定和移除標籤。

標籤名稱可以有任何值，只要它以字母或底線開頭，後面可選擇性地接著字母數字和 _ 字元，例如，^[a-zA-Z_][0-9a-zA-Z_]*。只有內建標籤才允許以底線 _ 字元開頭。

如何使用自定義標籤取決於您。您可以在叢集上設定自定義標籤來標記叢集的位置。例如，在叢集上設定名為 location 的自定義標籤，其值為 EMEA。

上一步首頁上一層下一步