API 认证到 Graphistry 服务器#

graphistry.register() 是用于验证您的 Graphistry 客户端的全局方法。它设置您的 API 凭据，指定要连接的服务器，并配置身份验证设置。在使用服务器进行任何 Graphistry API 调用（例如 .plot()）之前，应调用此函数。

在底层，它管理通过Graphistry REST API使用JWT会话令牌。同样，它简化了使用高级可选模式（如SSO）的过程。

基本用法#

要注册，请导入Graphistry并调用graphistry.register()：

import graphistry

# Register with default Graphistry Hub using username/password
graphistry.register(api=3, username="my_username", password="my_password")

默认情况下，这将连接到Graphistry Hub（hub.graphistry.com），使用https协议，并设置api=3以使用最新的API版本。您可以根据需要覆盖服务器、认证详细信息和其他设置。

核心概念#

个人账户与组织账户#

个人账户：用于个人使用，通常在Graphistry Hub上。
组织账户：通过角色和权限进行管理，通常在企业的上下文中。

user_info = graphistry.user()
print(user_info.get("organization"))  # Returns organization info or None

服务器配置#

默认服务器: 默认情况下，graphistry.register() 连接到 Graphistry Hub，包括用于可视化分析的 免费GPU层。
自定义服务器: 如果使用私有部署，请指定server参数以连接到您的自定义服务器。

# Connect to a custom server
graphistry.register(
    api=3,
    server="my_custom_graphistry_server.com",
    username="my_username",
    password="my_password"
)

协议配置#

TLS (HTTPS): 通信默认使用https以确保安全通信。
非TLS (HTTP): 如果您的服务器不支持TLS，请将protocol参数设置为“http”。

# Use HTTP protocol without TLS
graphistry.register(
    api=3,
    protocol="http",
    server="my_custom_graphistry_server.com",
    username="my_username",
    password="my_password"
)

认证方法#

graphistry.register() 支持多种认证方法：

用户名和密码:

graphistry.register(api=3, username="my_username", password="my_password")

个人密钥ID & 密钥（用于脚本或自动化）：

graphistry.register(api=3, personal_key_id="my_key_id", personal_key_secret="my_key_secret")

单点登录 (SSO)（适用于企业用户）：
graphistry.register(api=3, idp_name="my_idp_name", sso_opt_into_type="browser")
SSO认证选项：sso_opt_into_type可以是“browser”、“display”或None（默认为print）。

路由配置#

服务器路由：默认情况下，服务器API和浏览器UI请求通过同一个服务器进行路由。
自定义浏览器路由：通过client_protocol_hostname覆盖浏览器路由。

# Override browser routing
graphistry.register(
    api=3,
    server="my_api_server.com",
    username="my_username",
    password="my_password",
    client_protocol_hostname="https://my_ui_server.com"
)

高级功能#

JWT 会话处理#

graphistry.register() 在认证后建立一个JWT会话。会话令牌会自动管理，以便用于未来的API调用。

获取当前的JWT令牌#

要检索当前的JWT令牌，您可以在注册后使用以下命令：

# Get the current JWT token
current_token = graphistry.api_token()
print(current_token)

会话期间，令牌会根据需要自动刷新。

详细参数参考#

username (Optional[str]): 您的Graphistry账户用户名。
password (Optional[str]): 您的Graphistry账户密码。
personal_key_id (Optional[str]): 您的个人密钥ID，用于安全访问。
personal_key_secret (Optional[str]): 对应的个人密钥。
server (Optional[str]): 要连接的Graphistry服务器的URL（例如，hub.graphistry.com 或自定义服务器）。
protocol (Optional[str]): 使用的协议（https 或 http），默认为 https。
api (Optional[int]): 使用的API版本（始终设置为3）。
client_protocol_hostname (Optional[str]): 覆盖浏览器的协议/主机名。
org_name (Optional[str]): 用于SSO认证的组织名称。
idp_name (Optional[str]): 用于单点登录（SSO）的身份提供商（IdP）。
sso_opt_into_type (Optional[str]): 如何显示SSO URL（“browser”、“display”或None）。

示例#

使用用户名和密码注册#

import graphistry

graphistry.register(
    api=3,
    username="my_username",
    password="my_password"
)

使用个人密钥ID和密钥注册#

import graphistry

graphistry.register(
    api=3,
    personal_key_id="my_key_id",
    personal_key_secret="my_key_secret"
)

使用SSO注册（具有特定IdP的组织）#

import graphistry

graphistry.register(
    api=3,
    org_name="my_org_name",
    idp_name="my_idp_name",
    sso_opt_into_type="browser"
)

使用自定义服务器和协议注册#

import graphistry

graphistry.register(
    api=3,
    protocol="http",
    server="my_custom_server.com",
    username="my_username",
    password="my_password"
)

使用自定义浏览器路由注册#

import graphistry

graphistry.register(
    api=3,
    server="my_api_server.com",
    username="my_username",
    password="my_password",
    client_protocol_hostname="https://my_ui_server.com"
)

—

最佳实践#

安全性：始终使用安全协议（https）并验证证书。
认证: 使用 personal_key_id 和 personal_key_secret 进行自动化。
单点登录: 对于组织，确保正确的org_name，如果需要，idp_name。
会话管理: 该库自动处理会话令牌；启用内存存储时，请确保安全处理凭据。

故障排除#

连接错误：检查服务器和协议参数，并确保您的网络允许访问。
认证失败: 验证凭据。对于SSO，确保org_name和idp_name是正确的。
SSL问题：验证服务器证书是否有效，或考虑禁用SSL验证（certificate_validation=False），尽管不推荐这样做。

API 认证到 Graphistry 服务器

目录