specklepy入門｜Python SDKでSpeckleClient認証・operations.send/receive

この記事は Speckle を Python から扱う SDK「specklepy」の入門です。GUI での操作（send／receive）を理解した前提で、同じことをコードから行う方法を見ていきます。.NET で書きたい場合は .NET SDK を参照してください。データ構造は オブジェクトモデル が前提知識です。

1インストール

specklepy は PyPI で配布されており、pip でインストールできます。

pip install specklepy

Python の仮想環境（venv など）を用意してから入れると、依存関係を他プロジェクトと分離できて安全です。バージョンによって API が変わることがあるため、利用する Speckle Server の世代に合った specklepy のバージョンを選びます。

2SpeckleClient と認証

サーバとやり取りする入口が SpeckleClient です。接続先サーバの URL を指定してクライアントを作り、アクセストークンで認証します。トークンはコードに直書きせず、環境変数などから読み込むのが安全です。

import os
from specklepy.api.client import SpeckleClient
from specklepy.api.credentials import get_account_from_token

# サーバの URL（自前ホスティングなら社内サーバの URL）
client = SpeckleClient(host="https://app.speckle.systems")

# 環境変数からトークンを読む
token = os.environ["SPECKLE_TOKEN"]
client.authenticate_with_token(token)

認証に成功すると、このクライアントを通じて Project / Model / Version の情報取得や、データの送受信が行えるようになります。トークンには必要最小限のスコープだけを付けておきましょう。

3Base オブジェクトを作る

送るデータは Base オブジェクトとして組み立てます。Base は動的にプロパティを追加できるので、必要な属性を自由に持たせられます。

from specklepy.objects.base import Base

# ルートとなる Base を作り、プロパティを動的に付与する
obj = Base()
obj.name = "sample wall"
obj.height = 3000          # 単位の前提はプロジェクトで統一しておく
obj.category = "Walls"

幾何（点・線・メッシュなど）を扱う場合は、specklepy が提供するジオメトリ用のクラスを使って Base のツリーに組み込みます。大きな子要素は detach の考え方（オブジェクトモデル 参照）に沿って分離されます。

4ServerTransport と send / receive

データの実体（オブジェクトツリー）をどこへ送る・どこから受け取るかを指定するのが Transport です。サーバとの送受信には ServerTransport を使います。送受信そのものは operations.send / operations.receive で行います。

from specklepy.transports.server import ServerTransport
from specklepy.api import operations

# 対象プロジェクト（旧 Stream）の ID を指定して Transport を作る
project_id = "xxxxxxxxxx"
transport = ServerTransport(client=client, stream_id=project_id)

# Base オブジェクトを送ると、その内容のルート id（ハッシュ）が返る
object_id = operations.send(base=obj, transports=[transport])

# 受け取りは id を指定して復元する
received = operations.receive(obj_id=object_id, remote_transport=transport)

ここで返ってくる object_id は、オブジェクトモデル で説明した内容ハッシュです。この id を指す Version を別途作成すると、GUI のコネクタで送ったときと同じくバージョン履歴に現れます（Version の作成は GraphQL API 経由で行います）。

5典型的な使いどころ

specklepy はバッチ処理や連携の自動化に向きます。代表的な用途は次のとおりです。

具体的な往復連携の文脈は Revit ⇄ Speckle を、サーバ側で処理を自動実行する仕組みは Automate を参照してください。同等のことを C# で書く場合は次の .NET SDK に進みます。

6注意点

大量データを扱うときは、転送量やサーバ負荷に配慮し、detach や送信範囲の絞り込みを活用します。これらの効率の裏側は オブジェクトモデル のハッシュ・重複排除を参照してください。

→次に読む