连接器示例

Tableau 连接器文件包括：

• 清单文件，用于告知 Tableau 有关连接器的信息。Tableau 使用此文件中的名称将其添加到 UI 中的可用连接器列表中。

• Tableau 连接对话框文件可根据需要为此连接自定义连接对话框。

• Tableau 连接解析程序文件使用 JavaScript 文件创建与文件的连接，以定义和建立连接。

• Tableau 方言文件标识要使用的 SQL 方言。

Tableau 提供了一组基本的连接器文件，您可以使用这些文件来创建自己的自定义连接器。可以使用连接测试工具在生成连接器时验证连接器行为。

此图显示了连接器如何与 Tableau 和数据库进行交互。这些组件文件的详细信息和示例如下图所示。

以下大多数示例都使用 PostGre SQL 数据库的连接器，该数据库位于postgres_odbc或postgres_jdbc文件夹中。

清单文件

清单文件（清单.xml）通知 Tableau 有关连接器的信息，并在“Tableau 连接”窗格中显示连接器名称。它是定义连接器类和说明的必需文件。类值是连接器的唯一键，在其他 XML 文件中用于应用其自定义项，并在 Tableau 工作簿中用于匹配连接类型。

每个连接器通常基于一个“类”（如 ODBC 或 JDBC），并提供其他自定义项。

• 类值是连接器的唯一键，在其他 XML 文件中用于应用其自定义项，并在 Tableau 工作簿中用于匹配连接类型。

• name 值在 Tableau Connect 窗格中显示连接器名称。

• 您还可以指定供应商信息。

• 公司名称值在“Tableau Connect”窗格上的连接器名称旁边显示连接器创建者的名称（例如，“连接器创建者名称”）。

• The support link value is the URL of a website where users of the connector can get support.

Tableau Connection Dialog File

The Tableau Connection Dialog file (.tcd) is optional. By default, your connector inherits a connection dialog from its parent (defined by superclass You can use the TCD file to customize the connection dialog. For example, if you set show-ssl-check box to “true”, the Require SSL checkbox will display on the connection dialog.

Here’s an example:

Tableau Connector Resolver File

The Connector Resolver file (.tdr) is optional. Tableau uses it to create a connection to your data.

The TDR file calls these scripts (described in the following sections):

• Connection Builder

• Connection Properties

The TDR file also contains the connection-normalizer and the driver-resolver section. The connection-normalizer component defines what makes up a unique connection. An example of the component :

    
        
            server
            port
            dbname
            username
            password

Starting in Tableau 2021.1 a connector using Connection Dialog V2 can let the system determine at runtime the correct connection-normalizer by not defining it. See API Reference for more details.

The driver-resolver is only used for ODBC drivers. JDBC connectors can specify the driver name in the URL built by the connection builder JavaScript.

Tableau database connections have a unique type, the class attribute. For example, all Postgres connections have the same class. Each connection also has a set of connection attributes with unique values. Typically these attributes include the database server, username, and password. If the attributes and their values are identical then the connections are considered the same and can be reused and shared within the Tableau process.

Connection attributes pass values from the connection dialog or the saved Tableau workbook to the Connection Resolver. In turn, the Connection Resolver uses these attributes to format an ODBC or JDBC connection string.

    
        
            // This is the component number 4 in the diagram above
            
        
        
            // This is the component number 5 in the diagram above
            // It is only used for JDBC Connectors
            
        
        
            
                
                    server
                    port
                    dbname
                    username
                    password
                
            
        
    
    // The driver resolver defines the rules for locating the ODBC driver
    // You don't need a driver resolver for JDBC plugins
    
        
            PostgreSQL Unicode*

Connection Builder

Tableau uses the Connection Builder script (connectionBuilder.js) to create the ODBC connection string and the JDBC connection URL. The script maps attributes that define how the connection is configured. Some values – such as username, password, and database name – are user entries from the connection dialog. They are mapped to ODBC or JDBC connection string values that the driver (in this case, PostgresSQL) uses. Other attributes (such as BOOLSASCHAR and LFCONVERSION in this example) have values set to useful defaults. These depend on which driver you are using to connect to your database. You can use this script to set any other connection string options that you would like to pass to the driver.

This is an example Connection Builder script for ODBC:

(function dsbuilder(attr)
{
    var params = {};

    // The values below come from the connection dialog and are entered by the user.
    // Here they are mapped to the ODBC connection string values the the driver can use.
    params["SERVER"] = attr[connectionHelper.attributeServer];
    params["PORT"] = attr[connectionHelper.attributePort];
    params["DATABASE"] = attr[connectionHelper.attributeDatabase];
    params["UID"] = attr[connectionHelper.attributeUsername];
    params["PWD"] = attr[connectionHelper.attributePassword];
    params["BOOLSASCHAR"] = "0";

    // The values below can be set to useful defaults.
    params["LFCONVERSION"] = "0";
    params["UseDeclareFetch"] = "1";
    params["Fetch"] = "2048";

    var formattedParams = [];

    // The driver resolver is invoked below to find the matching ODBC driver
    formattedParams.push(connectionHelper.formatKeyValuePair(driverLocator.keywordDriver, driverLocator.locateDriver(attr)));

    for (var key in params)
    {
        // This formats the params map into a set of ODBC key value pairs
        formattedParams.push(connectionHelper.formatKeyValuePair(key, params[key]));
    }

    return formattedParams;
})

This is an example Connection Builder script for JDBC:

(function dsbuilder(attr) {
    var urlBuilder = "jdbc:postgresql://" + attr[connectionHelper.attributeServer] + ":" + attr[connectionHelper.attributePort] +
        "/" + attr[connectionHelper.attributeDatabase] + "?";

    return [urlBuilder];
})

Connection Properties

The Connection Properties script (connectionProperties.js) is optional. You need this script only if you’re using a JDBC driver.

This example is for a connector to Amazon Athena.

(function propertiesBuilder(attr) {
    //This script is only needed if you are using a JDBC driver.
    var params = {};

    // Set keys for properties needed for connecting using JDBC.
    var KEY_USER = "user";
    var KEY_PASSWORD = "password";
    var KEY_WAREHOUSE = "s3_staging_dir"

    // Set connection properties from existing attributes.
    params[KEY_USER] = attr[connectionHelper.attributeUsername];
    params[KEY_PASSWORD] = attr[connectionHelper.attributePassword];
    params[KEY_WAREHOUSE] = attr[connectionHelper.attributeWarehouse];

    //Format the attributes as 'key=value'. By default some values are escaped or wrapped in curly braces to follow the JDBC standard, but you can also do it here if needed.
    var formattedParams = [];
    for (var key in params) {
        formattedParams.push(connectionHelper.formatKeyValuePair(key, params[key]));
    }

    //The result will look like (search for jdbc-connection-properties in tabprotosrv.log):
    //"jdbc-connection-properties","v":{"password":"********","s3_staging_dir":"s3://aws-athena-s3/","user":"admin"}
    return formattedParams;
})

连接示例

Tableau Connection Resolver 文件 （.tdr） 会生成 ODBC ConnectString 或 JDBC Connection URL，您可以在 tabprotosrv.txt 中找到。

对于 ODBC，搜索 ConnectString 以查找类似于以下示例的内容：

ConnectString: DRIVER={PostgreSQL Unicode(x64)};SERVER=postgres;PORT=5432;DATABASE=TestV1;UID=test;PWD=********;BOOLSASCHAR=0;LFCONVERSION=0;UseDeclareFetch=1;Fetch=2048

对于 JDBC，搜索“连接 URL”以查找类似于以下示例的内容：

JDBCProtocol Connection URL: jdbc:postgresql://postgres:5342/TestV1

Tableau 方言文件

连接后，Tableau 使用您的 Tableau 方言文件 （.tdd） 来确定要为从数据库中检索数据而生成的 SQL。您可以在 TDD 文件中定义自己的方言，或者连接器可以从其父级（由超类定义）继承方言。如果您使用的是“odbc”或“jdbc”超类，则必须定义方言，因为这些超类没有方言。

下面是一个示例 Tableau 方言 （.tdd） 文件：