HIRO 7 图形 REST API 的 Hiro 客户端

Intended Audience
- Developers
License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3
- Python :: 3.7
Topic
- Software Development :: Libraries

项目描述

HIRO 图形 API 客户端

这是一个用于访问HIRO Graph数据的客户端库。

该库还包含用于处理WebSocket event-ws和action-wsAPI 的类。

要处理大量数据，请查看“hiro-batch-client”。-（PyPI：hiro-batch-client，GitHub：hiro-batch-client-python）

有关 HIRO 自动化的更多信息，请查看https://www.arago.co/

有关此库涵盖的 API 的更多信息，请参阅https://developer.hiro.arago.co/7.0/api/

目前，实施的是

HiroApp为了app
HiroAuth为了auth
HiroGraph为了graph
HiroIam为了iam
HiroKi为了ki
HiroAuthz为了authz
HiroVariables为了variables

对于 websockets

AbstractEventWebSocketHandler为了event-ws
AbstractActionWebSocketHandler为了action-ws

快速开始

要使用此库，您需要在https://id.arago.co/上拥有一个帐户并访问 OAuth Client-Id 和 Client-Secret 以访问 HIRO Graph。另请参阅https://developer.hiro.arago.co。

大多数文档都是在源代码中完成的。

HiroGraph 示例

使用简单图形 api 客户端的示例：

from hiro_graph_client import PasswordAuthTokenApiHandler, HiroGraph

hiro_client: HiroGraph = HiroGraph(
    api_handler=PasswordAuthTokenApiHandler(
        root_url="https://core.arago.co",
        username='',
        password='',
        client_id='',
        client_secret=''
    )
)

# The commands of the Graph API are methods of the class HIROGraph.
# The next line executes a vertex query for instance. 
query_result = hiro_client.query('ogit\\/_type:"ogit/MARS/Machine"')

print(query_result)

TokenApiHandler

对 HIRO Graph 的授权是通过令牌完成的。AbstractTokenApiHandler这些标记由该库中的类型类处理。每个 Hiro-Client-Object ( HiroGraph, HiroApp, 等) 在构造时都需要某种 TokenApiHandler。

此 TokenApiHandler 还负责确定 API 调用的最新端点。custom_endpoints=您可以在构造时使用 dict 参数提供自定义的端点列表。

也可以通过headers=构造函数中的 dict 参数设置自定义的标题列表。这些将更新内部标题。标题名称可以以任何大写/小写形式提供。

该库提供以下 TokenApiHandlers：

FixedTokenApiHandler

在构造时使用预设令牌生成的简单 TokenApiHandler。无法更新其令牌。

EnvironmentTokenApiHandler

从运行时环境中读取环境变量（默认为HIRO_TOKEN）的 TokenApiHandler。仅当环境变量在外部发生更改时才会更新其令牌。

PasswordAuthTokenApiHandler

此 TokenApiHandler 登录到 HiroAuth 后端并从登录凭据中获取令牌。这也是唯一一个 TokenApiHandler（到目前为止）在过期时自动尝试从后端更新令牌。

本文档中的所有代码示例都可以互换使用这些 TokenApiHandler，具体取决于提供此类令牌的方式。

上面的 HiroGraph 示例与另一个自定义的 TokenApiHandler：

from hiro_graph_client import EnvironmentTokenApiHandler, HiroGraph

hiro_client: HiroGraph = HiroGraph(
    api_handler=EnvironmentTokenApiHandler(
        root_url="https://core.arago.co"
    )
)

# The commands of the Graph API are methods of the class HIROGraph.
# The next line executes a vertex query for instance. 
query_result = hiro_client.query('ogit\\/_type:"ogit/MARS/Machine"')

print(query_result)

带有附加参数的示例：

from hiro_graph_client import EnvironmentTokenApiHandler, HiroGraph

hiro_client: HiroGraph = HiroGraph(
    api_handler=EnvironmentTokenApiHandler(
        root_url="https://core.arago.co",
        env_var='_TOKEN',
        headers={
            'X-Custom-Header': 'My custom value'
        },
        custom_endpoints={
            "graph": "/api/graph/7.2",
            "auth": "/api/auth/6.2"
        },
        client_name="HiroGraph (testing)"  # Will be used in the header 'User-Agent'
    )
)

# The commands of the Graph API are methods of the class HIROGraph.
# The next line executes a vertex query for instance. 
query_result = hiro_client.query('ogit\\/_type:"ogit/MARS/Machine"')

print(query_result)

令牌处理程序共享

当您需要访问 HIRO 的多个 API 时，请在 API 对象之间共享 TokenApiHandler，以避免对 HIRO 进行不必要的令牌和版本信息请求。TokenApiHandler 将requests.Session在它们之间共享令牌和版本请求处理以及令牌字符串本身。

from hiro_graph_client import HiroGraph, HiroApp, PasswordAuthTokenApiHandler

hiro_api_handler = PasswordAuthTokenApiHandler(
    root_url="https://core.arago.co",
    username='',
    password='',
    client_id='',
    client_secret=''
)

hiro_client: HiroGraph = HiroGraph(
    api_handler=hiro_api_handler
)

hiro_app_client: HiroApp = HiroApp(
    api_handler=hiro_api_handler
)

连接共享

您还可以让 TokenApiHandler 共享一个公共连接会话，而不是让它们每个人创建自己的。这在令牌必须在外部设置或经常更改（即每个线程每个用户一个令牌）的多线程环境中可能证明是有用的。这也确保了版本请求仅在连接初始化时发生一次。

使用参数pool_maxsize和pool_block进一步调整连接参数以并行访问后端。请参阅请求会话对象requests.adapters.HTTPAdapter以及和的 Python 文档GraphConnectionHandler。

from hiro_graph_client import HiroGraph, HiroApp, FixedTokenApiHandler, GraphConnectionHandler

connection_handler = GraphConnectionHandler(
    root_url="https://core.arago.co",
    pool_maxsize=200,                     # Optional: Max pool of cached connections for this connection session
    pool_block=True,                      # Optional: Do not allow more parallel connections than pool_maxsize
    client_name="Your Graph Client 0.0.1" # Optional: Will be used in the header 'User-Agent'
)

# Work with token of user 1

user1_client: HiroGraph = HiroGraph(
    api_handler=FixedTokenApiHandler(
        connection_handler=connection_handler,
        token='token user 1'
    )
)

# Work with token of user 2 (Shared Token Handler)

user2_api_handler = FixedTokenApiHandler(
    connection_handler=connection_handler,
    token='token user 2'
)

user2_client: HiroGraph = HiroGraph(
    api_handler=user2_api_handler
)

hiro_app_client: HiroApp = HiroApp(
    api_handler=user2_api_handler
)

Token Handler Sharing中编写的所有内容仍然适用。

SSL 配置

SSL 参数是使用类配置的SSLConfig。此类将给定的参数转换为requestsPython 库的必需字段（参数cert和verify那里）。此配置提供给 TokenApiHandlers，并且也将由附加到它的客户端使用。

如果未设置，requests将使用库的默认设置，即使用系统默认值验证任何服务器证书。

示例：禁用验证

from hiro_graph_client import EnvironmentTokenApiHandler, HiroGraph, SSLConfig

hiro_client: HiroGraph = HiroGraph(
    api_handler=EnvironmentTokenApiHandler(
        root_url="https://core.arago.co",
        # Disable any verification.
        ssl_config=SSLConfig(verify=False)
    )
)

query_result = hiro_client.query('ogit\\/_type:"ogit/MARS/Machine"')

print(query_result)

示例：设置自定义 SSL 证书

from hiro_graph_client import EnvironmentTokenApiHandler, HiroGraph, SSLConfig

hiro_client: HiroGraph = HiroGraph(
    api_handler=EnvironmentTokenApiHandler(
        root_url="https://core.arago.co",
        # Set custom certification files. If any of them are omitted, system defaults will be used.
        ssl_config=SSLConfig(
            cert_file="<path to client certificate file>",
            key_file="<path to key file for the client certificate>",
            ca_bundle_file="<path to the ca_bundle to verify the server certificate>"
        )
    )
)

query_result = hiro_client.query('ogit\\/_type:"ogit/MARS/Machine"')

print(query_result)

图形客户端“HiroGraph”

Graph Client 使用起来非常简单，因为此类的所有公共方法都表示 Graph API中的 API 调用。文档也可以在源代码中找到。有些调用有点复杂，下面会更详细地解释：

附件

要将数据上传到这样的顶点，请使用HiroGraph.post_attachment(data=...). 该参数data=将直接requests作为 requests.post(data=...). 要流式传输数据，请设置data为类型的对象IO。requests有关更多详细信息，请参阅 Python 库的文档。

下载附件是分块完成的，因此在流式传输这些数据时可以避免内存中的大量数据。每个块默认为 64k。

要将此类附件流式传输到文件，请参见以下示例：

ogit_id = '<ogit/_id of a vertex>'
data_iter = hiro_client.get_attachment(ogit_id)

with io.start("attachment.bin", "wb") as file:
    for chunk in data_iter:
        file.write(chunk)

要读取内存中的完整数据，请参见以下示例：

ogit_id = '<ogit/_id of a vertex>'
data_iter = hiro_client.get_attachment(ogit_id)

attachment = b''.join(data_iter)

网络套接字

该库包含使使用 HIRO WebSocket 协议更容易的类。它们处理身份验证、异常等等。

这些类不处理消息的缓冲，因此程序员有责任确保传入的消息要么被快速处理，要么被缓冲以避免阻塞 websocket。这些类是线程安全的，因此可以在其自己的线程中异步处理每个传入消息，并在需要时让这些线程发回结果（请参阅Action WebSocket中的多线程示例）。

关闭 WebSocket

要彻底关闭这些 WebSockets ( ws )，请考虑以下场景：

默认行为

库对KeyboardInterrupt (SIGINT) 做出反应，并在收到此类中断时通过关闭消息干净地关闭 WebSocket。如果收到另一个信号（如 SIGTERM），程序将立即停止，而不会向服务器返回任何关闭消息。

信号处理

安装信号处理程序时，您需要使用ws.signal_stop()来关闭 WebSocket。不要使用 ws.stop()否则关闭过程会死锁。这是因为信号中断是在与ws.run_forever()相同的线程中执行的。

例子：

import signal

[...]

with ActionWebSocket(api_handler=FixedTokenApiHandler('HIRO_TOKEN')) as ws:
    def signal_handler(signum, handler):
        ws.signal_stop()


    signal.signal(signal.SIGINT, signal_handler)
    signal.signal(signal.SIGTERM, signal_handler)
    signal.signal(signal.SIGHUP, signal_handler)  # This signal might not be available on MS Windows 

    ws.run_forever()

从单独的线程关闭

当从另一个线程而不是运行ws.run_forever()的线程关闭 WebSocket 时，您应该使用ws.stop()。这确保了关闭是同步的，并且ws.stop()将在 WebSocket 关闭后返回。

事件 WebSocket

此 websocket 接收有关更改与某个过滤器匹配的顶点的通知。

另见event-ws 的 API 描述

例子：

import threading

from hiro_graph_client.clientlib import FixedTokenApiHandler
from hiro_graph_client.eventswebsocket import AbstractEventsWebSocketHandler, EventMessage, EventsFilter


class EventsWebSocket(AbstractEventsWebSocketHandler):

    def on_create(self, message: EventMessage):
        """ Vertex has been created """
        print("Create:\n" + str(message))

    def on_update(self, message: EventMessage):
        """ Vertex has been updated """
        print("Update:\n" + str(message))

    def on_delete(self, message: EventMessage):
        """ Vertex has been removed """
        print("Delete:\n" + str(message))


events_filter = EventsFilter(filter_id='testfilter', filter_content="(element.ogit/_type=ogit/MARS/Machine)")

with EventsWebSocket(api_handler=FixedTokenApiHandler('HIRO_TOKEN'),
                     events_filters=[events_filter],
                     query_params={"allscopes": "false", "delta": "false"}) as ws:
    ws.run_forever()  # Use KeyboardInterrupt (Ctrl-C) to exit.

如果您不设置参数scope=，将使用您帐户的默认范围。如果您需要手动设置范围，请使用以下命令：

[...]

api_handler = FixedTokenApiHandler('HIRO_TOKEN')

default_scope = api_handler.decode_token()['data']['default-scope']

with EventsWebSocket(api_handler=api_handler,
                     events_filters=[events_filter],
                     scopes=[default_scope],
                     query_params={"allscopes": "false", "delta": "false"}) as ws:
    ws.run_forever()  # Use KeyboardInterrupt (Ctrl-C) to exit.

动作 WebSocket

此 websocket 接收有关已在 KI 中触发的操作的通知。使用它来编写您自己的自定义操作处理程序。

参见action-ws 的 API 描述

简单的例子：

import threading

from hiro_graph_client.actionwebsocket import AbstractActionWebSocketHandler
from hiro_graph_client.clientlib import FixedTokenApiHandler


class ActionWebSocket(AbstractActionWebSocketHandler):

    def on_submit_action(self, action_id: str, capability: str, parameters: dict):
        """ Message *submitAction* has been received """

        # Handle the message
        print(f"ID: {action_id}, Capability: {capability}, Parameters: {str(parameters)}")

        # Send back message *sendActionResult*
        self.send_action_result(action_id, "Everything went fine.")

    def on_config_changed(self):
        """ The configuration of the ActionHandler has changed """
        pass


with ActionWebSocket(api_handler=FixedTokenApiHandler('HIRO_TOKEN')) as ws:
    ws.run_forever()  # Use KeyboardInterrupt (Ctrl-C) to exit.

使用线程执行器的多线程示例：

import threading
import concurrent.futures

from hiro_graph_client.actionwebsocket import AbstractActionWebSocketHandler
from hiro_graph_client.clientlib import FixedTokenApiHandler, AbstractTokenApiHandler


class ActionWebSocket(AbstractActionWebSocketHandler):

    def __init__(self, api_handler: AbstractTokenApiHandler):
        """ Initialize properties """
        super().__init__(api_handler)
        self._executor = None

    def start(self) -> None:
        """ Initialize the executor """
        super().start()
        self._executor = concurrent.futures.ThreadPoolExecutor()

    def stop(self, timeout: int = None) -> None:
        """ Shut the executor down """
        if self._executor:
            self._executor.shutdown()
        self._executor = None
        super().stop(timeout)

    def handle_submit_action(self, action_id: str, capability: str, parameters: dict):
        """ Runs asynchronously in its own thread. """
        print(f"ID: {action_id}, Capability: {capability}, Parameters: {str(parameters)}")
        self.send_action_result(action_id, "Everything went fine.")

    def on_submit_action(self, action_id: str, capability: str, parameters: dict):
        """ Message *submitAction* has been received. Message is handled in thread executor. """
        if not self._executor:
            raise RuntimeError('ActionWebSocket has not been started.')
        self._executor.submit(ActionWebSocket.handle_submit_action, self, action_id, capability, parameters)

    def on_config_changed(self):
        """ The configuration of the ActionHandler has changed """
        pass


with ActionWebSocket(api_handler=FixedTokenApiHandler('HIRO_TOKEN')) as ws:
    ws.run_forever()  # Use KeyboardInterrupt (Ctrl-C) to exit.

变更日志

v5.3.0

通过 static 解码任何令牌decode_token_ext()。

/api/auth/6.6 的更改：

撤销令牌的能力。
识别access_token并_TOKEN在令牌结果中。
从类 TokenInfo 中删除过时的方法fresh()，因为现在每个令牌刷新都会默认发出一个新的 refresh_token。

v5.2.5

[错误修正]当没有expires_at 可用于令牌时， clientlib.TokenInfo.expired()中的计算现在按预期返回False 。以前的版本会引发异常。

v5.2.4

在 AbstractAPI 中合并标题而不是替换它们。

v5.2.3

永久删除 accept_all_certs。直接使用 SSLConfig 中的标志。

v5.2.2

调试的python代码文档。
修复了版权声明。

v5.2.1

由于https://pypi.org/project/hiro-graph-client/上的错误文档而更新

v5.2.0

将连接会话与令牌处理程序分开。介绍GraphConnectonHandler可以在TokenApiHandlers 和 API-Classes 之间共享的类。
更新了文档。

v5.1.0

通过 requests.Session 使用连接池。
- 设置pool_connections=1，pool_maxsize=10默认情况下（后者可以更改）。
- 阻止pool_block任何超过pool_maxsize.
删除过时accept_all_certs()的。
修复了 Makefile 目标中的 pytest。
requests.Session添加了有关pool_maxsize文档的信息。

v5.0.0

在https://github.com/arago/hiro-batch-client-pythonbatchclient.py将其作为自己的项目外部化。

v4.9.0

添加了问题的批处理。handle_vertices_combined现在识别_issue_data与顶点直接相关的问题。
更新了文档。

v4.8.0

重构websocketlib.py：
- 删除了不必要的额外线程。
- 通过信号和线程调试 WebSockets 的关闭。
- 更新的文档：
  - 关于信号处理。
  - 完全关闭 WebSockets。
  - 调整了 WebSockets 的示例代码。
允许-或_作为测试标签上的内部版本号分隔符，即t4.8.0_0现在t4.8.0-0处理相同。

v4.7.5

[预算修复] 在 AbstractActionWebSocketHandler 中处理self.submitStore并self.resultStore正确关闭。当启动失败时，它们可能根本没有被初始化。

v4.7.4

[错误修正] 使用 PasswordAuthTokenHandler 和 refresh_token 时捕获 401。当这发生触发重试时引发 TokenUnauthorizedError。

v4.7.3

重构HiroGraphBatch. 删除了过时的方法。

v4.7.2

修复了 IAM API 中对 patch() 方法的错误调用。

v4.7.1

HiroGraph更新了一些过时的代码文档。
更新了图表查询HiroGraph：
- 对于顶点和 gremlin 查询：跳过查询有效负载中不必要的字段。
- count向顶点查询添加参数。
将默认 _client_name 重命名为hiro-graph-client（PyPI 上的库名称）。

v4.7.0

内容/媒体类型处理
- WrongContentTypeError当返回意外（或丢失）的 Content-Type 时抛出。
- 检查构造 HTTPError 的错误结果的 Content-Type。
错误处理
- 单独的错误消息提取，因此可以按 API 覆盖。
- 尝试通过猜测它们的错误消息可能在哪里来处理不同的消息格式。
- 拦截 API 的特殊错误消息ki。
- log_communication_on_error在响应中检测到错误时启用通信记录的标志。
max_tries向 TokenHandlers添加参数。

v4.6.2

添加了新 API 的文档

v4.6.1

更新了 CHANGELOG.md

v4.6.0

添加了以下 API：
- KI
- 授权Z
- 变量
使用返回字典列表的 API 方法调整返回值类型。

v4.5.2

错误修复

以前的版本错误地将 True 和 False 翻译为“True”和“False”，而 URL 查询中需要“true”和“false”（小写）。固定的。

v4.5.1

添加decode_token()以解码嵌入在 HIRO 令牌中的信息。

v4.5.0

GitHub 存储库从重命名python-hiro-clients为hiro-client-python. 没有其他技术变化。

v4.4.0

添加了 IAM 客户端
更新了 Graph 客户端和 Auth 客户端
put_binary 现在允许返回简单的字符串。（即用于头像图像更新）。

v4.3.0

添加 SSL 配置

v4.2.14

删除了 websocketlib 中使用反向运算符的错误。
更新了 README.md 中的安装说明。

v4.2.13

query_params={'allscopes': 'true'}如果要为 EventWebSockets 启用它，则需要显式设置。如果在 query_params 中忽略它，它将被添加为 'allscopes': 'false'。

v4.2.12

使用类型来确保query_params=WebSockets 的类型是Dict[str, str].
设置query_params={'allscopes': 'false'}为 EventWebSocket 的默认值。

v4.2.11

调试的 EventWebSocket 处理。
设置范围或过滤器失败时中止连接。

v4.2.10

向 EventWebSockets 添加范围。

v4.2.9

v4.2.8 中的功能文档

v4.2.8

WebSockets 有新的选项query_params可以将任意查询参数添加到初始 websocket 请求中。

v4.2.7

更改为AbstractAuthenticatedWebSocketHandler：

介绍run_forever()which 将在加入阅读器线程后返回。当另一个线程调用stop()（正常退出）或发生内部错误时，可能会发生这种情况，直接在尝试连接时，令牌无效且无法刷新，或在内部读取器线程中引发的任何其他异常。

这确保了当 websocket 读取器线程不存在时主线程不会继续。
send()启用跨多个线程的并行执行。
确保只有一个线程通过调用来触发重启restart()。
通过 . 检查活动的 websocket 阅读器线程is_active()。
更新 README.md 中的 websocket 示例。

通用的

更新 README.md 以显示client_name.

v4.2.6

不需要包 uuid - python 已经提供了它

v4.2.5

向后端发送有效的关闭消息。
引入参数client_name以给连接命名并User-Agent更轻松地设置标题。

v4.2.4

更新了 CHANGELOG.md。

v4.2.3

强化客户端库。删除了一些无值错误。

v4.2.2

将参数remote_exit_codes引入AbstractAuthenticatedWebSocketHandler.

v4.2.1

_backoff()通过不使用sleep()but来避免阻塞线程threading.Condition.wait()。

v4.2.0

实现 websocket 协议
- 事件-ws
- 动作ws

v4.1.3

使用 yield from 而不是 return

v4.1.2

删除了二进制数据双倍收益的错误

v4.1.1

仅在启用 logging.DEBUG 时记录请求/响应

v4.1.0

向命令添加了时间序列处理handle_vertices_combined

v4.0.0

AbstractTokenApiHandler
- 更好的令牌处理。
- 通过调用 /api/version 解析图形 api 端点。
  - 能够自定义标题。标头以不区分大小写的方式处理，并提交给大写的请求。
  - 能够覆盖内部端点。
AbstractIOCarrierwith现在适用于语句。
添加BasicFileIOCarrier.
已删除ApiConfig。
重命名了几个内部类。
更好的错误信息。
HTTP 安全协议日志记录。
修复了令牌的时间戳创建。
乔的建议 - 谢谢乔！

v3.1.0

在客户端库中分离 API。目前，支持的 API 有：
- HiroGraph：https ://core.arago.co/help/specs/?url=definitions/graph.yaml
- HiroAuth：https ://core.arago.co/help/specs/?url=definitions/auth.yaml
- HiroApp：https ://core.arago.co/help/specs/?url=definitions/app.yaml
在二进制传输中使用正确的标头。
向 HiroGraph 添加了 gremlin 和多 id 查询。

v3.0.0

重命名类以匹配其他地方的文档（即 Graphit -> HiroGraph、GraphitBatch -> HiroGraphBatch）。
当 refresh_token 过期时捕获令牌过期错误。
带有示例的文档

hiro-graph-client 5.3.0

导航

项目链接

统计数据

Meta

Maintainers

分类