Python - PyDDB

外部ユーザーにはメモ - 次のセクションのリンクの多くは、内部アプリケーションを参照してください。 サポートについては、プロジェクトチームに相談してください。

pyddbパッケージは、構文を簡素化して利便性機能を実装することにより、非開発者が DDB と対話する明確な方法を提供します。

このガイドでは、パッケージのインストールとクイックスタート、およびパッケージとその機能の完全な参照をカバーします。

特徴

DDB API エンドポイントと対話するためのインターフェイスを大幅に簡素化することに加えて、ライブラリは他の便利な機能を提供します。

認証

クライアントは、クライアントがインスタンス化されたときにユーザーに ARUP 資格情報を促し、必要に応じてトークンを自動的に更新します。

簡素化された API と実装

ライブラリは、自動化されたワークフローを作成したい初心者 Python ユーザー向けに構築されています。

すべてのマイクロサービスエンドポイントを、一貫したインターフェイスを備えた単一のライブラリに簡素化しました。 これは、学ぶべきことが少なく、簡単に始めることができることを意味します。

再実行スクリプトを保持することができ、重複のチェックと更新の実行を処理します。 通常、スクリプトは、プロジェクト番号を変更するだけで、他のプロジェクトで使用できます。

DDB の分類法を簡単に探索できます

DDB には独自の分類法があります。新しいタイプの資産またはパラメーターを作成することはできません。

このライブラリは、名前または UUID で既存の分類法を検索する方法を提供します。

完全にテストされました

このライブラリは、DDB API の現在および将来のバージョンに対して完全にテストされているため、自信を持って始めることができます。

ページネーション

デフォルトでは、エンドポイントはデータの最初のページを返します。 このライブラリはページネーションを処理し、すべてのデータを取得します。

IDE サポート

ライブラリは完全に入力されているため、AutoComplete を取得し、IDE でチェックを入力できます。

インストールとセットアップ

1. Python 3.10+（App Store）が必要です - パッケージを実行するために必要です。
2. Git（Service Desk）が必要です - パッケージをインストールするために必要です。
3. arup 電子メールを使用した github アカウントが必要です - パッケージをインストールするために必要です。
4. 推奨される Visual Studio Code（App Store） - コードを作成するための推奨環境。

上記をインストールしたら、Visual Studio Code を開き、作業内容を保存するフォルダーを開きます。

Bash ターミナルを開き、次のコマンドを実行します。

仮想環境を作成します

python -m venv .venv

仮想環境をアクティブにします

source .venv/Scripts/activate

ddb Python sdks をインストールします

pip install keyring artifacts-keyring python-dateutil
pip install ddb-user-service \
ddb-reference-data-service \
ddb-qa-service \
ddb-parameter-service \
ddb-parameter-metadata-service \
ddb-environment-context-service \
ddb-comments-service \
-i https://ovearup.pkgs.visualstudio.com/_packaging/ddb/pypi/simple/

PyDDB パッケージをインストールします

pip install git+https://github.com/arup-group/PyDDB.git

クイックスタート

データを取得します

DDB からデータを取得することは、プロジェクトオブジェクトの適切な方法を呼び出すのと同じくらい簡単です。 これにより、ページネーションとメタデータを使用してオブジェクトを返すことができます。 を見てください API リファレンス 詳細については。

必要なライブラリの部分をインポートします。

from pyddb import DDB, env, Project, ParameterType

クライアントをインスタンス化して環境を設定します。

ddb = DDB(env.sandbox)

既存の DDB プロジェクトを取得します：

my_project = Project.get_by_number(project_number="21515700")

プロジェクトからデータを取得します。

project_parameters = my_project.get_parameters()
project_assets = my_project.get_assets()
project_sources = my_project.get_sources()

分類からデータを取得します：

all_parameter_types = ParameterType.get_all()
some_parameter_types = ParameterType.search('area')
my_parameter_type = ParameterType.get("Plot area")

データの投稿

必要なライブラリの部分をインポートします。

from pyddb import DDB, env, Project, ParameterType, AssetType, Unit, Source, Parameter, Asset

クライアントをインスタンス化して環境を設定します。

ddb = DDB(env.sandbox)

プロジェクトを作成するか、既存のプロジェクトを取得します。

project = Project.put("21515700")

投稿する資産を定義します。

assets = [
    my_site := Asset.create(
        asset_type=AssetType.get("site"),
        name="My DDB Site",
        parent=None,
    ),
    my_building := Asset.create(
        asset_type=AssetType.get("building"),
        name="My DDB Building",
        parent=my_site,
    )
]

投稿するパラメーターを定義します。

parameters = [
    Parameter.create(
        parameter_type=ParameterType.get("Plot area"),
        value=240,
        unit=Unit.get("m²"),
        parent=my_site,
        source=Source.create(
            source_type = SourceType.get("Derived Value"),
            title="My source title",
            reference="My source reference",
        ),
    )
]

データを投稿してください：

project.post_assets(assets)
project.post_parameters(parameters)

これらの各ポストメソッドは、投稿しているものを返し、複製データを追加しません。 新しいパラメーターを投稿しても、値、単位、またはソースが変更されていない場合、既存のパラメーターをオーバーライドしません。

これは、これらの方法を使用して自動化されたワークフローを作成できることを意味します。

API リファレンス

これらのドキュメントはクラスごとに分類されており、使用方法の説明と例を提供します。 このライブラリには、さまざまな目的に役立つ 2 つの主要なクラスがあります。

データクラス ： これらは当社のデータの値を表し、プロジェクトデータとの対話のために投稿して削減するものです。 これらは通常、分類法のクラスに結び付けられるため、どのようなデータを使用しているかがわかります。

分類クラス ： 「パラメータ型」や「AssetType」などのこれらのクラスは、チームによって決定されます。 これらは、データを分類し、コンテキストを提供する方法です。

要するに、データクラスはあなたが作業しているデータであり、分類クラスはそれを分類する方法です。 あなたも私たちを探索することができます 用語集 使用する用語の詳細については。

データクラス

DDB と 計画 クラスは、ライブラリの主なエントリポイントです。 DDBクラスは、クライアントをインスタンス化して環境を設定するために、すべてのスクリプトで使用されます。 DDBクラスはプロジェクト間のデータへのアクセスに使用され、{Projectクラスは特定のプロジェクトのデータにアクセスするために使用されます。

DDB

DDB クラスは、クライアントのメインクラスです。 クライアントをインスタンス化して環境を設定するために使用されます。 すべてのスクリプトは、作業中の環境でクライアントをインスタンス化する必要があります。

from pyddb import DDB, env

ddb_client = DDB(env.sandbox)

これを使用して、プロジェクト間のデータにアクセスできるようになりました。 返されるデータの量を減らすために、非常に特定のクエリを使用することをお勧めします。

all_projects = ddb_client.get_projects()

all_plot_areas = ddb_client.get_parameters(
    parameter_type_id=[
        ParameterType.get("Plot area").id
    ]
)

計画

プロジェクトクラスは、特定のプロジェクトのデータにアクセスするために使用されます。 プロジェクト番号をget_by_numberまたはputメソッドに渡すことでインスタンス化されます。

from pyddb import DDB, env, Project

DDB(env.sandbox)

my_project = Project.get_by_number("00000000")
my_project = Project.put("00000000")

これら 2 つの方法の違いは、get_by_numberが DDB に存在する場合にのみプロジェクトを返すことです。 putが存在しない場合、プロジェクトが作成されます。

ソース

ソースクラスは、ソースを作成して DDB に投稿するために使用されます。 新しいソースは、createメソッドへのソースタイプ、タイトル、および参照を渡すことによりインスタンス化されます。

from pyddb import DDB, env, Project, Source, SourceType

DDB(env.sandbox)

my_source = Source.create(
    title="My source title",
    reference="My source reference",
    source_type=SourceType.get("Derived Value"),
)

ソースは、post_sourcesでProjectメソッドにソースのリストを渡すことにより、DDB に投稿できます。

my_project = Project.put("00000000")
my_project.post_sources([my_source])

プロジェクトのソースは、get_sourcesでProjectメソッドを呼び出すことで再確認できます。

project_sources = my_project.get_sources()

これは、過去のプロジェクトからソースを取得し、新しいプロジェクトでそれらを再利用するのが非常に簡単であることを意味します。

資産

Assetクラスは、アセットを DDB に作成および投稿するために使用されます。 新しい資産は、createメソッドに名前、アセットタイプ、および親を渡すことによりインスタンス化されます。

注意すべき重要なことの 1 つは、DDB では、同じ名前、タイプ、親の 2 つの資産を持つことができないことです。 これは、単一のサイトに同じ名前の 2 つの建物がないことを意味します。 このライブラリは、このロジックを使用して、複製資産が作成されないようにし、代わりにスクリプトが再実行された場合に既存の資産を返します。

from pyddb import DDB, env, Project, Asset, AssetType

DDB(env.sandbox)

my_asset = Asset.create(
    name="My asset name",
    asset_type=AssetType.get("Site"),
)

my_other_asset = Asset.create(
    name="My other asset name",
    asset_type=AssetType.get("Building"),
    parent=my_asset,
)

yet_another_asset = Asset.create(
    asset_sub_type=AssetSubType.get("Cooling"),
    parent=my_other_asset,
)

資産を作成するためのいくつかのルールがあります。

• アセットはAssetTypeまたはAssetSubTypeのいずれかを必要とするため、それがどんな資産であるかがわかります。
• AssetSubTypeのない資産には名前が必要です。
• 資産は、資産タイプの階層に従う必要があります。 たとえば、Buildingアセットでは、親としてSiteアセットを持つ必要があります。

AssetTypeクラスを探索して、階層を理解するか、DDB UI を使用できます。

アセットは、post_assetsでProjectメソッドに資産のリストを渡すことにより、DDB に投稿できます。

my_project = Project.put("00000000")
my_project.post_assets([my_asset, my_other_asset, yet_another_asset])

プロジェクトのアセットは、get_assetsでProjectメソッドを呼び出すことで取得できます。

project_assets = my_project.get_assets()

これは、過去のプロジェクトから資産を取得し、新しいプロジェクトでそれらを再利用するのが非常に簡単であることを意味します。

パラメーター

Parameterクラスは、パラメーターを DDB に作成および投稿するために使用されます。 新しいパラメーターは、パラメータータイプ、値、単位、ソース、および親をcreateメソッドに渡すことによりインスタンス化されます。

パラメーターを投稿する前に、SourceおよびAssetクラスに精通したいと思うでしょう。

from pyddb import DDB, env, Project, Parameter, ParameterType, Source, SourceType, Asset, AssetType

DDB(env.sandbox)

my_source = Source.create(
    title="My source title",
    reference="My source reference",
    source_type=SourceType.get("Derived Value"),
)

my_site = Asset.create(
    name="My site name",
    asset_type=AssetType.get("Site"),
)

my_parameter = Parameter.create(
    parameter_type=ParameterType.get("Height"),
    value=100,
    unit="m",
    source=my_source,
    parent=my_site,
)

パラメーターは、post_parametersでProjectメソッドにパラメーターのリストを渡すことにより、DDB に投稿できます。

my_project = Project.put("00000000")

my_project.post_parameters([my_parameter])

Parameterは、ParameterTypeだけで作成できます。これは、投稿すると、値なしで空白のパラメーターを作成します。 値で投稿すると、ライブラリは値、ユニット、またはソースが変更されているかどうかを確認し、パラメーターがある場合はパラメーターを更新します。

また、値を持つパラメーターと一緒にコメントを投稿することもできます。

parameter_with_comment = Parameter.create(
    parameter_type=ParameterType.get("Location"),
    value="Glasgow, Scotland",
    source=my_source,
    comment="Includes the city of Glasgow and the surrounding area.",
)

分類クラス

これらのクラスは、データを分類したさまざまな方法を表しています。

例として、プロジェクトには何千ものParameterデータクラスがあり、これらはすべて、いくつかのParameterType分類クラスによって分類されています。 これは、ParameterオブジェクトをParameterTypeの「エリア」とともにオブジェクトにすることができます。

これらのクラスは、データにコンテキストを提供し、一貫した構造を提供し、作業を容易にするために使用されます。

これらのクラスには、それらと対話するために使用する 3 つの一般的な方法があります。

get_all - これにより、そのタイプのすべての分類オブジェクトが DDB で返されます。

search - これにより、検索用語に一致する分類オブジェクトのリストが返されます。

get - これにより、名前または uuid で単一の分類オブジェクトが返されます。

ソースの種類

DDB には、ソースタイプの分類法があります。 これらの例には、「仮定」、「派生価値」、および「産業ガイダンス」が含まれます。

from pyddb import DDB, env, SourceType

DDB(env.sandbox)

all_source_types = SourceType.get_all()
my_source_type = SourceType.get("Derived Value")

my_source_type.id
my_source_type.name

資産タイプ

DDB には、資産タイプの分類法があります。 これらの例には、「サイト」、「建物」、「スペース」、「ブリッジ」、「トンネル」、「道路」が含まれます。

from pyddb import DDB, env, AssetType

DDB(env.sandbox)

all_asset_types = AssetType.get_all()
my_asset_type = AssetType.get("Site")

my_asset_type.id
my_asset_type.name

一部の資産タイプにはサブタイプがあります。 asset_sub_type boolean プロパティを確認して、サブタイプがあるかどうかを確認できます。

if my_asset_type.asset_sub_type:
    sub_types = my_asset_type.get_sub_types()

アセットサブタイプ

DDB の分類法は、資産タイプのサブタイプへのさらなる分類をサポートしています。 資産タイプにサブタイプがある場合、そのタイプのすべてのインスタンスは、サブタイプの 1 つとして分類する必要があります。

例として、「建物システム」AssetTypeには、「加熱」、「冷却」、「照明」など、いくつかのサブタイプがあります。 このタイプのすべての資産は、これらのサブタイプの 1 つである必要があります。

from pyddb import DDB, env, AssetSubType

DDB(env.sandbox)

all_asset_sub_types = AssetSubType.get_all()
my_asset_sub_type = AssetSubType.get("Heating")

my_asset_sub_type.id
my_asset_sub_type.name
my_asset_sub_type.asset_type_id

パラメータータイプ

DDB には、パラメータータイプの分類があります。 これらの例には、「夏の屋内乾燥電球温度」、「弾力性の弾性率」、「最後の検査日」が含まれます。

これらは、Parametersを分類し、できるユニットや可能なデータ型など、いくつかのルールを適用するために使用されます。

from pyddb import DDB, env, ParameterType

DDB(env.sandbox)

all_parameter_types = ParameterType.get_all()
my_parameter_type = ParameterType.get("Modulus of elasticity")

my_parameter_type.id
my_parameter_type.name
my_parameter_type.data_type
my_parameter_type.unit_type

アイテムタイプ

ItemTypeは、AssetType、ParameterType、潜在的にAssetSubTypeの組み合わせです。

これらは私たちのチームによって作成され、ParameterTypesでAssetsとAssetTypeに基づいて、異なるAssetSubTypeを異なるItemTypeで利用可能にします。 ParameterTypesクラスを使用して、異なるAssetTypesで使用できる を確認できます。

from pyddb import DDB, env, ItemType

DDB(env.sandbox)

all_item_types = ItemType.get_all()

site_item_types = ItemType.get_by_asset_type(AssetType.get("Site"))

ItemTypes利用可能なOptionsのリストなど、データにさらに具体的なルールを適用することができます。 たとえば、ItemType 'フィールドタイプ'をParameterType 'site'にAssetType 'フィールドタイプを表すItemTypeがあります。 このOptionsには、「z_Optionのリストがあり、「ブラウンフィールド」や「グリーンフィールド」など、選択できるさまざまな種類のフィールドを表します。 これは、DDB では、「サイト」資産上の「フィールドタイプ」のすべての値がこれら 2 つのオプションのいずれかである必要があることを意味します。

for item_type in site_item_types:
    if item_type.has_options:
        options = item_type.get_options()

オプション

Parameterは、特定のItemTypeのItemTypesに選択できる値です。 これらは、異なるParameterTypesに対して許可される値のプリセットリストです。

「値」プロパティを介して値にアクセスできます。

for option in options:
    print(option.value)

ユニット型

DDB には、ユニットタイプの分類があります。 これらの例には、「温度」、「長さ」、「面積」、「ボリューム」が含まれます。

これらにより、「摂氏」や「華氏」など、類似のユニットを「温度」単位タイプにグループ化できます。

unit_typeには、ParameterTypeプロパティがあり、に使用できるユニットを制限するために使用されます。

from pyddb import DDB, env, UnitType

DDB(env.sandbox)

all_unit_types = UnitType.get_all()
my_unit_type = UnitType.get("Temperature")

my_unit_type.id
my_unit_type.name

特定のUnitTypeに対してすべてのユニットを取得することもできます。

my_unit_type = UnitType.get('Length')
length_units = my_unit_unit.get_units()

ユニットシステム

DDB には、ユニットシステムの分類があります。 これらの例には、「Si」、「Imperial」、および「General」が含まれます。

これらにより、ユニットをさらに分類できます。

from pyddb import DDB, env, UnitSystem

DDB(env.sandbox)

all_unit_systems = UnitSystem.get_all()
my_unit_system = UnitSystem.get("General")

my_unit_system.id
my_unit_system.name

特定のUnitSystemに対してすべてのユニットを取得することもできます。

my_unit_system = UnitSystem.get('General')
general_units = my_unit_unit.get_units()

ユニット

DDB にはユニットの分類があります。 これらの例には、「M」、「KG」、および「FT」が含まれます。

from pyddb import DDB, env, Unit
DDB(env.sandbox)

all_units = Unit.get_all()
my_unit = Unit.get("m")

my_unit.id
my_unit.symbol

ロールタイプ

ロールタイプ DDB プロジェクトへのさまざまなタイプのアクセスを定義します。 単一のユーザーは複数の役割を持つことができます。

さまざまな役割タイプは次のとおりです。

Admin - ユーザー許可を変更するため

Reader - プロジェクトデータを読むため

Editor - プロジェクトデータの編集用

Checker - QA ステータスを更新するため

Approver - データを承認するため

RoleTypeはEnumオブジェクトです。

from pyddb import DDB, env, Project, RoleType

DDB(env.sandbox)

project = Project.put('00000000')

project.put_user_roles([
    (RoleType.Admin, '[email protected]'),
    (RoleType.Editor, '[email protected]'),
])

鬼ごっこ

Tagsは、データの整理に使用され、フィルタリングと検索に役立ちます。 これらの例には、「Google」、「Scotland」、および「Mechanical」が含まれます。

from pyddb import DDB, env, Tag, Project, Asset, Parameter

DDB(env.sandbox)

all_tags = Tag.get_all()
my_tag = Tag.get("Google")

project = Project.put('00000000')
some_asset = project.get_assets()[0]
some_parameter = some_asset.get_parameters()[0]

project.post_tags([my_tag])
some_asset.post_tags([my_tag])
some_parameter.post_tags([my_tag])

タグタイプ

Tagsは、TagTypesによってグループ化されます。 これらの例には、「クライアント」、「地域」、「ワークステージ」が含まれます。

from pyddb import DDB, env, TagType

DDB(env.sandbox)

all_tag_types = TagType.get_all()
my_tag_type = TagType.get("Client")

client_tags = my_tag_type.get_tags()