DDB文档

# Python- PyDDB

注意外部用户 - 以下部分中的许多链接涉及内部应用程序。 请与您的项目团队联系以寻求支持。

pyddb软件包为非开发人员提供了一种清晰的方法，可以通过简化语法和实现便利性功能来与 DDB 进行交互。

本指南将涵盖包装的安装和快速启动，以及包装及其功能的完整参考。

# 特征

除了简化与 DDB API 端点交互的接口外，该库还提供了其他有用的功能：

验证

当客户实例化并根据需要自动刷新令牌时，客户端将提示用户获得 ARUP 凭据。

简化的 API 和实施

该库是为想要创建自动化工作流程的初学者 python 构建的。

我们将所有微服务端点简化为具有一致接口的单个库。 这意味着学习少，很容易开始。

您可以保留重新设计的脚本，我们将处理重复的检查并为您执行任何更新。 通常，仅通过更改项目编号，就可以在其他项目上使用脚本。

轻松探索 DDB 分类学

DDB 具有自己的分类法：您不能仅仅创建一种新型的资产或参数。

该库提供了通过名称或 UUID 搜索我们现有的分类法的方法。

经过全面测试

该库对 DDB API 的当前和未来版本进行了全面测试，因此您可以自信地开始。

分页

默认情况下，我们的端点将返回数据的第一页。 该库处理分页并为您检索所有数据。

IDE 支持

该库已完全键入，因此您可以自动完成并在 IDE 中输入检查。

# 安装和设置

  1. 需要 Python 3.10+（App Store） - 运行包装所需。

  2. 需要 git（服务台） - 安装包装。

  3. 需要带有 ARUP 电子邮件的 GitHub 帐户 - 需要安装软件包。

  4. 推荐的 Visual Studio 代码（App Store） - 编写代码的推荐环境。

安装完上述内容后，打开 Visual Studio Code 并打开您想要存储工作的文件夹。

打开 Bash 终端并运行以下命令：

创建虚拟环境

python -m venv .venv

激活虚拟环境

source .venv/Scripts/activate

安装 DDB Python SDK

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 \
ddb-template-service \
-i https://pkgs.dev.azure.com/ovearup/_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 参考

这些文档按课堂分解，并提供了应如何使用它们的描述和示例。

在此库中，我们有两种主要类型的类型，它们具有不同的目的：

数据类 ：

这些代表了我们数据的值，并且是您将发布和撤销以与项目数据进行交互的内容。

这些通常与分类类别相关，因此我们知道我们正在使用哪种数据。

分类类别 ：

这些类，例如“参数类型”或“ 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")

这两种方法之间的区别在于，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方法来实例化新资产。

要注意的一件事是，在 DDB 中，您不能拥有两个具有相同名称，类型和父母的资产。 这意味着一个站点不能拥有两座具有相同名称的建筑物。

该库使用此逻辑来防止创建重复资产，而如果脚本重新运行，则将返回现有资产。

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方案的。

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

可以通过在Project上调用get_assets方法来重述项目的资产。

project_assets = my_project.get_assets()

这意味着从过去的项目中获取资产并将其重复使用在新项目中非常容易。

# 范围

Project类用于创建和将参数发布到 DDB。 通过将参数类型，值，单位，源和父级传递到Parameter方法来实例化。

在发布参数之前，您需要熟悉create和Source类。

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,
)

可以通过将参数列表传递给Asset的post_parameters方法来发布到 DDB。

my_project = Project.put("00000000")
my_project.post_parameters([my_parameter])

只需使用_211即可创建一个Project，当发布时，它将创建一个无需任何值的空白参数。

当张贴一个值时，库将检查值，单位或源是否已更改并更新参数（如果有）。

我们还可以将评论与我们的参数一起使用值。

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.",
)

# 分类类别

这些类代表了我们对数据进行分类的不同方式。

例如，我们的项目中有成千上万的_212数据类，并且这些数据类都被一些Parameter分类类别分类。

这可能是具有“区域”的ParameterType的数百个Parameter对象。

这些类用于为数据提供上下文，提供一致的结构并使其更易于使用。

所有这些类都有 3 种常见方法，您将使用这些方法与它们进行交互：

ParameterType-这将返回 DDB 中该类型的所有分类对象。

Parameter-这将返回匹配搜索词的分类对象列表。

ParameterType-这将以名称或 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

一些资产类型具有亚型。 您可以检查他们的get_all布尔属性，以查看它们是否具有子类型。

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

# 资产亚型

DDB 分类法支持将资产类型的进一步分类为子类型。

当资产类型具有子类型时，该类型的所有实例必须归类为子类型之一。

例如，“建筑系统” search有几种子类型，包括“加热”，“冷却”和“照明”。

这种类型的所有资产都必须是这些子类型之一。

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 对参数类型具有分类学。

这些例子包括“夏季室内干灯泡温度”，“弹性模量”，“最后检查日期”。

这些用于对我们的get进行分类，并将某些规则应用于它们，例如它们可以拥有的单元或可能是数据类型。

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

# 物品种类

asset_sub_type是AssetType，Parameters和ItemType的组合。

这些是由我们的团队创建的，并根据AssetType和ParameterType在不同的AssetSubType上提供不同的ParameterTypes。

我们可以使用Assets班来查看哪些AssetType可用于不同的AssetSubType。

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"))

ItemType允许我们将更具体的规则应用于我们的数据，例如可用的ParameterTypes列表。

例如，可能会有一个AssetTypes代表ItemTypes“站点”上的Options“字段类型”。

这个ItemType可以包含ParameterType的列表，该列表代表可以选择的不同类型的字段，例如“ Brownfield”或“ Greenfield”。

这意味着在 DDB 中，“站点”资产上的所有“字段类型”的值必须是这两个选项之一。

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

# 选项

AssetType是可以为某个ItemType的Options选择的值。

这些是用于不同Option允许的值的预设列表。

您可以通过“值”属性访问其值：

for option in options:
    print(option.value)

# 单位类型

DDB 对单位类型具有分类学。

这些示例包括“温度”，“长度”，“区域”和“音量”。

这些使我们能够分组相似的单位，例如“摄氏”和“华氏”单位类型。

Parameter具有ItemType属性，用于限制可用于该ItemTypes的单位。

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

您还可以为给定的ParameterTypes检索所有单元。

my_unit_type = UnitType.get('Length')

length_units = my_unit_unit.get_units()

# 单位系统

DDB 对单位系统具有分类学。

这些例子包括“ si”，“帝国”和“一般”。

这些使我们能够进一步对单位进行分类。

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

您还可以为给定的unit_type检索所有单元。

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 项目的不同类型的访问。

一个用户可以具有多个角色。

不同的角色类型是：

ParameterType-用于修改用户权限

UnitType-用于阅读项目数据

UnitSystem-用于编辑项目数据

Admin-用于更新质量检查状态

Reader-用于批准数据

Editor是Checker对象。

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]'),
])

# 标签

Approver用于组织我们的数据，对于过滤和搜索可能很有用。

这些示例包括“ Google”，“苏格兰”和“机械”。

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])

# 标签类型

RoleType由他们的Enum分组在一起。

这些示例包括“客户”，“区域”和“工作场所”。

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()
Last Updated: 2024/9/24 16:41:45

← Postman →