FastAPI Tableau

文档： https://rstudio.github.io/fastapitableau

源代码： https://github.com/rstudio/fastapitableau

FastAPI Tableau 允许您通过Tableau Analytics Extensions从Tableau工作簿中调用外部Python代码。为此，您需要使用FastAPI编写一个API，并进行一些小的修改。如果您还不熟悉FastAPI，我们建议您从他们的教程开始。

API从Tableau调用所需的主要更改是将FastAPI应用程序类替换为FastAPITableau。

# Base FastAPI
from fastapi import FastAPI
app = FastAPI()

# FastAPI Tableau
from fastapitableau import FastAPITableau
app = FastAPITableau()

当你执行此操作时，FastAPI Tableau 将将来自 Tableau 的请求从 /evaluate 端点重定向并转换为你的应用程序中定义的端点。它还会在你的 API 根目录中为 Tableau 用户显示文档，包括 Tableau 调用的复制粘贴代码示例。

在用 FastAPI Tableau 编写扩展之前，你应该熟悉 FastAPI。入门的好地方是 教程。 你还应该查看 FastAPI Tableau 扩展的限制，这些限制如下所述。

简单的 FastAPI Tableau 扩展

from typing import List

from fastapitableau import FastAPITableau

app = FastAPITableau(
    title="Simple Example",
    description="A *simple* example FastAPITableau app.",
    version="0.1.0",
)


@app.post("/capitalize")
def capitalize(text: List[str]) -> List[str]:
    capitalized = [t.upper() for t in text]
    return capitalized

如果你将此代码放入终端工作目录中名为 simple.py 的文件中，你可以使用 Uvicorn 在本地提供服务，通过调用 uvicorn simple:app --reload。

FastAPI Tableau 扩展支持有限的数据模型功能

与标准 FastAPI 应用程序相比，FastAPI Tableau 扩展有一些限制。其中一些是由于 Tableau 发送数据的方式造成的。我们将在此处描述已知的限制以及如何在这些限制内工作。

所有从 Tableau 接收数据的参数必须是 列表字段。 Tableau 在请求体中以 JSON 列的形式发送其数据，FastAPI 将其转换为等效的 Python 类型。兼容的类型是 List[str]、List[float]、List[int] 和 List[bool]。你可以将这些参数定义为端点函数的参数，或者作为 Pydantic 模型的字段。

你的端点也必须以兼容的列表类型返回数据，并且返回的数据长度必须与接收到的输入相同。 这个要求并不是由 FastAPI Tableau 强制的，但 Tableau 将扩展返回的数据映射到一个表列中。

你可以通过声明单个（非 List）参数在函数中使用查询参数。 FastAPI 假设任何 bool、float、int 或 str 变量都是查询参数。你可以在从 Tableau 调用 API 的 script 参数中使用这些变量。

将所有这些组合在一起，你可以在函数定义中声明任意数量的列表和单个参数。列表参数将来自 Tableau 数据对象，而单个参数可以在 Tableau 计算中设置。

例如，如果你想创建一个端点，用于将数据乘以用户提供的数字，你可以这样定义

@app.post("/multiply")
def multiply(numbers: List[float], multiplier: float) -> List[float]:
    result = [i * multiplier for i in numbers]
    return result

FastAPI Tableau 将自动为你的端点生成 Tableau 使用示例，使用你的类型注解，因此提供完整的类型注解将使从 Tableau 使用你的 API 更容易。

为端点提供额外的描述性元数据

你可以像在常规 FastAPI 应用程序中一样，在端点装饰器和文档字符串中添加额外的元数据。

@app.post(
    "/paste",
    summary="Parallel concatenation on two lists of strings",
    response_description="A list of concatenated strings",
)
def paste(first: List[str], second: List[str]) -> List[str]:
    """
    Given two lists of strings, iterate over them, concatenating parallel items.

    - **first**: the first list of strings
    - **second**: the second list of strings
    """
    result = [a + " " + b for a, b in zip(first, second)]
    return result

此元数据将显示在 Tableau 用户的文档中。

将扩展部署到 RStudio Connect

你可以使用 rsconnect-python 将 FastAPI Tableau 扩展部署到 RStudio Connect。详细文档可以在 这里 找到。

rsconnect deploy fastapi \
    --server https://connect.example.org:3939 \
    --api-key my-api-key \
    my_api_directory/

rsconnect-python 假设你的 API 是目录中唯一的 Python。为了获得最佳结果，请在同一目录中指定你的 API 的依赖关系，放入 requirements.txt 文件中。更多信息请查看 这里。

使用自签名证书

当使用自签名证书与 FastAPI Tableau 一起时，你必须让 Python 了解证书的路径。

将环境变量 REQUESTS_CA_BUNDLE 设置为您的证书文件路径。该变量由底层 Requests 库使用，并在此处进行了文档说明。

在 RStudio Connect 中，在内容设置面板的“变量”选项卡中设置环境变量（请参阅链接）。请注意，在 RStudio Connect 上运行的应用程序无法访问 /etc 目录，因此证书必须放在不同的位置，例如 /opt/python。

在 Tableau 中调用扩展端点

您可以将使用示例（SCRIPT_* 命令）复制并粘贴到 Tableau 的计算字段中（它生成正确的 URL），并用 Tableau 工作簿中的实际值替换参数占位符。

处理 Tableau 数据

我们发现，Tableau 中的一些实践可以确保您传递给 Tableau 扩展的数据被正确发送。

• 您必须在“分析”菜单下关闭“聚合度量”，以便 Tableau 将正确的值传递给扩展。如果此设置打开，Tableau 将向扩展发送聚合数据，这可能导致计算不准确。
• 关闭此值后，计算字段不允许您直接将原始值传递给扩展。这些值必须被包装在聚合函数中。由于我们已经关闭了“聚合度量”，这些函数实际上不会聚合数据。我们成功使用了 ATTR([VALUE_NAME])。

调试日志记录

要启用详细调试日志记录，将环境变量 FASTAPITABLEAU_LOG_LEVEL 设置为 DEBUG。