#### 5.6.6.4 版本令牌参考

[](<>)

以下讨论可作为对这些版本令牌元素的参考：

-   [版本标记函数](version-tokens-reference.html#version-tokens-routines)

-   [版本令牌系统变量](version-tokens-reference.html#version-tokens-system-variables)

##### 版本标记函数

Version Tokens 插件库包括几个函数。一组函数允许操作和检查服务器的版本令牌列表。另一组功能允许锁定和解锁版本令牌。这[`VERSION_TOKEN_ADMIN`](privileges-provided.html#priv_version-token-admin)特权（或已弃用的[`极好的`](privileges-provided.html#priv_super)特权）是调用任何版本令牌功能所必需的。

以下函数允许创建、更改、删​​除和检查服务器的版本令牌列表。的解释*`名单`*和*`令牌列表`*参数（包括空格处理）发生如中所述[第 5.6.6.3 节，“使用版本令牌”](version-tokens-usage.html)，它提供了有关指定标记的语法的详细信息以及其他示例。

-   [](<>) [`version_tokens_delete(*`名单`*)`](version-tokens-reference.html#function_version-tokens-delete)

    [](<>)[](<>)

    使用*`名单`*参数并返回指示操作结果的二进制字符串。*`名单`*是要删除的版本标记名称的分号分隔列表。

    ```
    mysql> SELECT version_tokens_delete('tok1;tok3');
    +------------------------------------+
    | version_tokens_delete('tok1;tok3') |
    +------------------------------------+
    | 2 version tokens deleted.          |
    +------------------------------------+
    ```

    的一个论点`空值`被视为空字符串，对令牌列表没有影响。

    [`version_tokens_delete()`](version-tokens-reference.html#function_version-tokens-delete)如果存在，则删除其参数中命名的标记。（删除不存在的令牌不是错误。）要完全清除令牌列表而不知道列表中有哪些令牌，请通过`空值`或不包含标记的字符串[`version_tokens_set()`](version-tokens-reference.html#function_version-tokens-set)：

    ```
    mysql> SELECT version_tokens_set(NULL);
    +------------------------------+
    | version_tokens_set(NULL)     |
    +------------------------------+
    | Version tokens list cleared. |
    +------------------------------+
    mysql> SELECT version_tokens_set('');
    +------------------------------+
    | version_tokens_set('')       |
    +------------------------------+
    | Version tokens list cleared. |
    +------------------------------+
    ```

-   [](<>) [`version_tokens_edit(*`令牌列表`*)`](version-tokens-reference.html#function_version-tokens-edit)

    [](<>)[](<>)

    使用*`令牌列表`*参数并返回指示操作结果的二进制字符串。*`令牌列表`*是一个分号分隔的列表`*`姓名`*=*`价值`*`指定要定义的每个标记的名称及其值的对。如果存在令牌，则使用给定值更新其值。如果令牌不存在，则使用给定值创建它。如果论据是`空值`或不包含标记的字符串，标记列表保持不变。

    ```
    mysql> SELECT version_tokens_set('tok1=value1;tok2=value2');
    +-----------------------------------------------+
    | version_tokens_set('tok1=value1;tok2=value2') |
    +-----------------------------------------------+
    | 2 version tokens set.                         |
    +-----------------------------------------------+
    mysql> SELECT version_tokens_edit('tok2=new_value2;tok3=new_value3');
    +--------------------------------------------------------+
    | version_tokens_edit('tok2=new_value2;tok3=new_value3') |
    +--------------------------------------------------------+
    | 2 version tokens updated.                              |
    +--------------------------------------------------------+
    ```

-   [](<>) [`version_tokens_set(*`令牌列表`*)`](version-tokens-reference.html#function_version-tokens-set)

    [](<>)[](<>)

    将服务器的版本令牌列表替换为在*`令牌列表`*参数并返回指示操作结果的二进制字符串。*`令牌列表`*是一个分号分隔的列表`*`姓名`*=*`价值`*`指定要定义的每个标记的名称及其值的对。如果论据是`空值`或不包含标记的字符串，则清除标记列表。

    ```
    mysql> SELECT version_tokens_set('tok1=value1;tok2=value2');
    +-----------------------------------------------+
    | version_tokens_set('tok1=value1;tok2=value2') |
    +-----------------------------------------------+
    | 2 version tokens set.                         |
    +-----------------------------------------------+
    ```

-   [](<>) [`version_tokens_show()`](version-tokens-reference.html#function_version-tokens-show)

     [](<>)[](<>)

    将服务器的版本标记列表作为二进制字符串返回，其中包含以分号分隔的列表`*`姓名`*=*`价值`*`对。

    ```
    mysql> SELECT version_tokens_show();
    +--------------------------+
    | version_tokens_show()    |
    +--------------------------+
    | tok2=value2;tok1=value1; |
    +--------------------------+
    ```

    以下函数允许锁定和解锁版本令牌：

-   [](<>) [`version_tokens_lock_exclusive(*`令牌名称`*[, *`令牌名称`*] ..., *`暂停`*)`](version-tokens-reference.html#function_version-tokens-lock-exclusive)

    [](<>)[](<>)

    获取一个或多个版本令牌上的独占锁，由名称指定为字符串，如果在给定的超时值内未获取锁，则会超时并出现错误。

    ```
    mysql> SELECT version_tokens_lock_exclusive('lock1', 'lock2', 10);
    +-----------------------------------------------------+
    | version_tokens_lock_exclusive('lock1', 'lock2', 10) |
    +-----------------------------------------------------+
    |                                                   1 |
    +-----------------------------------------------------+
    ```

-   [](<>) [`version_tokens_lock_shared(*`令牌名称`*[, *`令牌名称`*] ..., *`暂停`*)`](version-tokens-reference.html#function_version-tokens-lock-shared)

    [](<>)[](<>)

    获取一个或多个版本令牌上的共享锁，由名称指定为字符串，如果在给定的超时值内未获取锁，则会超时并出错。

    ```
    mysql> SELECT version_tokens_lock_shared('lock1', 'lock2', 10);
    +--------------------------------------------------+
    | version_tokens_lock_shared('lock1', 'lock2', 10) |
    +--------------------------------------------------+
    |                                                1 |
    +--------------------------------------------------+
    ```

-   [](<>) [`version_tokens_unlock()`](version-tokens-reference.html#function_version-tokens-unlock)

     [](<>)[](<>)

    释放在当前会话中获取的所有锁，使用[`version_tokens_lock_exclusive()`](version-tokens-reference.html#function_version-tokens-lock-exclusive)和[`version_tokens_lock_shared()`](version-tokens-reference.html#function_version-tokens-lock-shared).

    ```
    mysql> SELECT version_tokens_unlock();
    +-------------------------+
    | version_tokens_unlock() |
    +-------------------------+
    |                       1 |
    +-------------------------+
    ```

    锁定函数具有以下特征：

-   返回值非零表示成功。否则，会发生错误。

-   令牌名称是字符串。

-   与处理服务器令牌列表的函数的参数处理相比，令牌名称参数周围的空格不会被忽略，并且`=`和`;`字符是允许的。

-   可以锁定不存在的令牌名称。这不会创建令牌。

-   超时值是非负整数，表示在超时出现错误之前等待获取锁的时间（以秒为单位）。如果超时为 0，则没有等待，如果无法立即获取锁，则该函数会产生错误。

-   版本令牌锁定功能基于描述的锁定服务[第 5.6.9.1 节，“锁定服务”](locking-service.html).

##### 版本令牌系统变量

版本令牌支持以下系统变量。除非安装了版本令牌插件，否则这些变量不可用（请参阅[第 5.6.6.2 节，“安装或卸载版本令牌”](version-tokens-installation.html)）。

系统变量：

-   [](<>) [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)

    [](<>)[](<>)

    | 命令行格式 | `--version-tokens-session=值` |
    | ----- | ---------------------------- |
    | 系统变量 | `[version_tokens_session](version-tokens-reference.html#sysvar_version_tokens_session)` |
    | 范围 | 全球, 会话 |
    | 动态的 | 是的 |
    | [`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var)提示适用 | 不 |
    | 类型 | 细绳 |
    | 默认值 | `空值` |

    此变量的会话值指定客户端版本令牌列表，并指示客户端会话需要服务器版本令牌列表具有的令牌。

    如果[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)变量是`空值`（默认值）或具有空值，任何服务器版本令牌列表都匹配。（实际上，空值禁用匹配要求。）

    如果[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)变量具有非空值，其值与服务器版本令牌列表之间的任何不匹配都会导致会话发送到服务器的任何语句出错。在以下情况下会发生不匹配：

    -   中的令牌名称[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)服务器令牌列表中不存在值。在这种情况下，一个[`ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_vtoken_plugin_token_not_found)发生错误。

    -   中的令牌值[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)value 与服务器令牌列表中相应令牌的值不同。在这种情况下，一个[`ER_VTOKEN_PLUGIN_TOKEN_MISMATCH`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_vtoken_plugin_token_mismatch)发生错误。

        服务器版本令牌列表包含未在[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)价值。

        假设管理应用程序已将服务器令牌列表设置如下：

    ```
    mysql> SELECT version_tokens_set('tok1=a;tok2=b;tok3=c');
    +--------------------------------------------+
    | version_tokens_set('tok1=a;tok2=b;tok3=c') |
    +--------------------------------------------+
    | 3 version tokens set.                      |
    +--------------------------------------------+
    ```

    客户端通过设置它来注册它需要服务器匹配的令牌[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)价值。然后，对于客户端发送的每个后续语句，服务器都会根据客户端检查其令牌列表[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)值并在不匹配时产生错误：

    ```
    mysql> SET @@SESSION.version_tokens_session = 'tok1=a;tok2=b';
    mysql> SELECT 1;
    +---+
    | 1 |
    +---+
    | 1 |
    +---+

    mysql> SET @@SESSION.version_tokens_session = 'tok1=b';
    mysql> SELECT 1;
    ERROR 3136 (42000): Version token mismatch for tok1. Correct value a
    ```

    首先[`选择`](select.html)成功，因为客户端令牌`托克1`和`托克2`存在于服务器令牌列表中，并且每个令牌在服务器列表中具有相同的值。第二[`选择`](select.html)失败是因为，虽然`托克1`存在于服务器令牌列表中，它的值与客户端指定的值不同。

    此时，客户端发送的任何语句都会失败，除非服务器令牌列表发生更改以使其再次匹配。假设管理应用程序更改服务器令牌列表如下：

    ```
    mysql> SELECT version_tokens_edit('tok1=b');
    +-------------------------------+
    | version_tokens_edit('tok1=b') |
    +-------------------------------+
    | 1 version tokens updated.     |
    +-------------------------------+
    mysql> SELECT version_tokens_show();
    +-----------------------+
    | version_tokens_show() |
    +-----------------------+
    | tok3=c;tok1=b;tok2=b; |
    +-----------------------+
    ```

    现在客户端[`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)值与服务器令牌列表匹配，客户端可以再次成功执行语句：

    ```
    mysql> SELECT 1;
    +---+
    | 1 |
    +---+
    | 1 |
    +---+
    ```

-   [](<>) [`version_tokens_session_number`](version-tokens-reference.html#sysvar_version_tokens_session_number)

    [](<>)[](<>)

    | 命令行格式 | `--version-tokens-session-number=#` |
    | ----- | ----------------------------------- |
    | 系统变量 | `[version_tokens_session_number](version-tokens-reference.html#sysvar_version_tokens_session_number)` |
    | 范围 | 全球, 会话 |
    | 动态的 | 不 |
    | [`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var)提示适用 | 不 |
    | 类型 | 整数 |
    | 默认值 | `0` |

    此变量供内部使用。
