Python - PyDDB

Lưu ý cho người dùng bên ngoài - Nhiều liên kết trong phần sau đây đề cập đến các ứng dụng nội bộ. Vui lòng nói chuyện với nhóm dự án của bạn để được hỗ trợ.

Gói pyddb cung cấp một cách rõ ràng để những người không phát triển tương tác với DDB bằng cách đơn giản hóa cú pháp và thực hiện các tính năng thuận tiện.

Hướng dẫn này sẽ bao gồm cài đặt và bắt đầu nhanh chóng của gói, cũng như tham chiếu đầy đủ về gói và các tính năng của nó.

Đặc trưng

Besides greatly simplifying the interface for interacting with the DDB API endpoints, the library provides other useful features:

Xác thực

Khách hàng sẽ nhắc người dùng cho thông tin đăng nhập Arup của họ khi máy khách được khởi tạo và tự động làm mới mã thông báo khi cần thiết.

API đơn giản hóa và triển khai

Thư viện được xây dựng cho người dùng python người dùng muốn tạo quy trình công việc tự động.

Chúng tôi đã đơn giản hóa tất cả các điểm cuối microservice vào một thư viện với giao diện nhất quán. Điều này có nghĩa là có ít hơn để học và thật dễ dàng để bắt đầu.

Bạn có thể giữ các tập lệnh chạy lại và chúng tôi sẽ xử lý kiểm tra các bản sao và thực hiện bất kỳ bản cập nhật nào cho bạn. Thông thường các tập lệnh có thể được sử dụng trên các dự án khác chỉ bằng cách thay đổi số dự án.

Dễ dàng khám phá phân loại DDB

DDB has it's own taxonomy: you can't just create a new type of asset or parameter.

Thư viện này cung cấp các cách tìm kiếm thông qua phân loại hiện tại của chúng tôi theo tên hoặc UUID.

Được kiểm tra đầy đủ

Thư viện này được kiểm tra đầy đủ so với các phiên bản hiện tại và tương lai của API DDB, vì vậy bạn có thể bắt đầu với sự tự tin.

Phân trang

Theo mặc định, các điểm cuối của chúng tôi sẽ trả về trang đầu tiên của dữ liệu. Thư viện này xử lý phân trang và lấy tất cả dữ liệu cho bạn.

Hỗ trợ IDE

Thư viện được gõ đầy đủ, vì vậy bạn có thể tự động hoàn thành và gõ kiểm tra IDE của mình.

Cài đặt và thiết lập

1. Yêu cầu Python 3.10+ (App Store) - Yêu cầu chạy gói.

2. Yêu cầu Git (Bàn dịch vụ) - Yêu cầu cài đặt gói.

3. Yêu cầu tài khoản GitHub với email Arup - Yêu cầu cài đặt gói.

4. Mã Visual Studio được đề xuất (App Store) - Môi trường được đề xuất để viết mã.

Khi bạn đã cài đặt xong phần trên, hãy mở Visual Studio Code và mở thư mục bạn muốn lưu trữ tác phẩm của mình vào đó.

Mở thiết bị đầu cuối Bash và chạy các lệnh sau:

Tạo một môi trường ảo

python -m venv .venv

Kích hoạt môi trường ảo

source .venv/Scripts/activate

Cài đặt 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 \
-i https://ovearup.pkgs.visualstudio.com/_packaging/ddb/pypi/simple/

Cài đặt gói PyDDB

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

Bắt đầu nhanh

Nhận dữ liệu

Nhận dữ liệu từ DDB đơn giản như gọi phương thức thích hợp trên đối tượng dự án.

Điều này sẽ xử lý phân trang và trả lại các đối tượng với siêu dữ liệu. Nhìn vào Tham khảo API để biết thêm thông tin.

Import the parts of the library you need:

from pyddb import DDB, env, Project, ParameterType

Instantiate the client and set the environment:

ddb = DDB(env.sandbox)

Get an existing ddb project:

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

Get data from the project:

project_parameters = my_project.get_parameters()

project_assets = my_project.get_assets()

project_sources = my_project.get_sources()

Get data from the taxonomy:

all_parameter_types = ParameterType.get_all()

some_parameter_types = ParameterType.search('area')

my_parameter_type = ParameterType.get("Plot area")

Đăng dữ liệu

Import the parts of the library you need:

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

Instantiate the client and set the environment:

ddb = DDB(env.sandbox)

Create a project or get an existing one:

project = Project.put("21515700")

Define the assets you want to post:

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

Define the parameters you want to post:

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

Post the data:

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

Mỗi phương thức bài đăng này sẽ trả về những gì họ đang đăng và không thêm dữ liệu trùng lặp. Đăng các tham số mới sẽ không ghi đè các tham số hiện có nếu giá trị, đơn vị hoặc nguồn không thay đổi.

Điều này có nghĩa là các phương pháp này có thể được sử dụng để tạo ra các quy trình công việc tự động.

Tham khảo API

These docs are broken down by class and provide a description and example of how they should be used.

In this library, we have two main types of classes that serve different purposes:

Các lớp dữ liệu :

These represent the values of our data and are what you will be posting and retreiving to interact with your project data.

These will typically be tied to the taxonomy classes so we know what kind of data we are working with.

Các lớp phân loại :

These classes, such as 'ParameterType' or 'AssetType', are determined by our team. These are ways of categorising our data and giving it context.

Nói tóm lại, các lớp dữ liệu là dữ liệu bạn đang làm việc và các lớp phân loại là cách chúng tôi phân loại nó.

Bạn cũng có thể khám phá bảng chú giải Để biết thêm thông tin về các điều khoản chúng tôi sử dụng.

Các lớp dữ liệu

Các DDB Và Dự án Các lớp học là điểm nhập chính cho thư viện.

Lớp DDB được sử dụng trong mỗi tập lệnh để khởi tạo máy khách và đặt môi trường.

Lớp DDB được sử dụng để truy cập dữ liệu giữa các dự án, trong khi lớp Project được sử dụng để truy cập dữ liệu trên một dự án cụ thể.

DDB

Lớp DDB là lớp chính cho máy khách. Nó được sử dụng để khởi tạo máy khách và đặt môi trường. Tất cả các tập lệnh nên khởi tạo khách hàng với môi trường họ đang làm việc.

from pyddb import DDB, env
ddb_client = DDB(env.sandbox)

Bây giờ bạn có thể sử dụng điều này để truy cập dữ liệu giữa các dự án.

Bạn nên sử dụng các truy vấn rất cụ thể để giảm lượng dữ liệu được trả về.

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

Dự án

Lớp dự án được sử dụng để truy cập dữ liệu trên một dự án cụ thể. Nó được khởi tạo bằng cách chuyển số dự án cho các phương thức get_by_number hoặc put.

from pyddb import DDB, env, Project
DDB(env.sandbox)
my_project = Project.get_by_number("00000000")
my_project = Project.put("00000000")

Sự khác biệt giữa hai phương pháp này là get_by_number sẽ chỉ trả lại dự án nếu nó tồn tại trong DDB. put sẽ tạo dự án nếu nó không tồn tại.

Nguồn

Lớp nguồn được sử dụng để tạo và đăng các nguồn cho DDB. Một nguồn mới được khởi tạo bằng cách truyền loại nguồn, tiêu đề và tham chiếu đến phương thức 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"),
)

Các nguồn có thể được đăng lên DDB bằng cách chuyển một danh sách các nguồn cho phương thức post_sources trên Project.

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

Các nguồn trên một dự án có thể được thử lại bằng cách gọi phương thức get_sources trên Project.

project_sources = my_project.get_sources()

Điều này có nghĩa là rất dễ dàng để có được các nguồn từ một dự án trong quá khứ và tái sử dụng chúng trong một dự án mới.

Tài sản

Lớp Asset được sử dụng để tạo và đăng tài sản lên DDB. Một tài sản mới được khởi tạo bằng cách chuyển tên, loại tài sản và cha mẹ cho phương thức create.

Một điều quan trọng cần lưu ý là trong DDB, bạn không thể có hai tài sản có cùng tên, loại và cha mẹ. Điều này có nghĩa là một trang web không thể có hai tòa nhà có cùng tên.

Thư viện này sử dụng logic này để ngăn các tài sản trùng lặp được tạo và thay vào đó sẽ trả về các tài sản hiện có nếu các tập lệnh được chạy lại.

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

There are a few rules for creating assets:

• Tài sản cần một AssetType hoặc AssetSubType vì vậy chúng tôi biết đó là loại tài sản nào.

• Tài sản không có AssetSubType cần một tên.

• Tài sản cần tuân theo hệ thống phân cấp loại tài sản.

Ví dụ: tài sản Building cần có tài sản Site làm cha mẹ.

Bạn có thể khám phá lớp AssetType để hiểu về hệ thống phân cấp hoặc sử dụng UI DDB.

Tài sản có thể được đăng lên DDB bằng cách chuyển danh sách các tài sản cho phương thức post_assets trên Project.

my_project = Project.put("00000000")

my_project.post_assets([my_asset, my_other_asset, yet_another_asset])

Tài sản trên một dự án có thể được lấy lại bằng cách gọi phương thức get_assets trên Project.

project_assets = my_project.get_assets()

Điều này có nghĩa là rất dễ dàng để có được tài sản từ một dự án trong quá khứ và tái sử dụng chúng trong một dự án mới.

Tham số

Lớp Parameter được sử dụng để tạo và đăng các tham số lên DDB. Một tham số mới được khởi tạo bằng cách truyền loại tham số, giá trị, đơn vị, nguồn và cha mẹ cho phương thức create. Bạn sẽ muốn làm quen với các lớp Source và Asset trước khi đăng các tham số.

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

Các tham số có thể được đăng lên DDB bằng cách chuyển danh sách các tham số cho phương thức post_parameters trên Project.

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

Một Parameter có thể được tạo chỉ bằng một ParameterType, khi được đăng, sẽ tạo một tham số trống mà không có bất kỳ giá trị nào.

Khi được đăng với một giá trị, thư viện sẽ kiểm tra xem giá trị, đơn vị hoặc nguồn đã thay đổi và cập nhật tham số nếu nó có.

Chúng tôi cũng có thể đăng bình luận cùng với các tham số của chúng tôi với các giá trị.

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

Các lớp phân loại

Các lớp này đại diện cho các cách khác nhau mà chúng tôi đã phân loại dữ liệu của chúng tôi.

Ví dụ, chúng tôi có hàng ngàn lớp dữ liệu Parameter trong các dự án của chúng tôi và tất cả đều được phân loại bởi một vài lớp phân loại ParameterType.

Đây có thể là hàng trăm đối tượng Parameter với ParameterType của "khu vực".

Các lớp này được sử dụng để cung cấp bối cảnh cho dữ liệu, cung cấp cho nó cấu trúc nhất quán và giúp làm việc dễ dàng hơn.

All of these classes have 3 common methods that you will use to interact with them:

get_all - Điều này sẽ trả về tất cả các đối tượng phân loại thuộc loại đó trong DDB.

search - Điều này sẽ trả về một danh sách các đối tượng phân loại phù hợp với thuật ngữ tìm kiếm.

get - Điều này sẽ trả về một đối tượng phân loại duy nhất theo tên hoặc UUID.

Loại nguồn

DDB có phân loại cho các loại nguồn.

Ví dụ trong số này bao gồm 'giả định', 'giá trị xuất phát' và 'hướng dẫn ngành'.

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

Loại tài sản

DDB có phân loại cho các loại tài sản.

Ví dụ trong số này bao gồm 'trang web', 'tòa nhà', 'không gian', 'cầu', 'đường hầm' và 'đường'.

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

all_asset_types = AssetType.get_all()

my_asset_type = AssetType.get("Site")

my_asset_type.id

my_asset_type.name

Một số loại tài sản có phân nhóm. Bạn có thể kiểm tra thuộc tính asset_sub_type boolean của họ để xem chúng có phân nhóm không.

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

Phân nhóm tài sản

Phân loại DDB hỗ trợ phân loại thêm các loại tài sản thành các loại phụ.

Khi một loại tài sản có các loại phụ, tất cả các phiên bản thuộc loại đó phải được phân loại là một trong các loại phụ.

Ví dụ, 'hệ thống xây dựng' AssetType có một số loại phụ, bao gồm 'sưởi ấm', 'làm mát' và 'ánh sáng'.

Tất cả các tài sản thuộc loại này cần phải là một trong những loại phụ đó.

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

Loại tham số

DDB có phân loại cho các loại tham số.

Ví dụ trong số này bao gồm 'nhiệt độ bóng đèn khô trong nhà mùa hè', 'mô đun đàn hồi', 'ngày kiểm tra cuối cùng'.

Chúng được sử dụng để phân loại Parameters của chúng tôi và áp dụng một số quy tắc cho chúng, chẳng hạn như các đơn vị họ có thể có hoặc các loại dữ liệu mà chúng có thể có.

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

Loại vật phẩm

ItemType là sự kết hợp của AssetType, ParameterType và có khả năng là AssetSubType.

Chúng được tạo ra bởi nhóm của chúng tôi và cung cấp các ParameterTypes khác nhau trên các Assets khác nhau dựa trên AssetType và AssetSubType của họ.

Chúng ta có thể sử dụng lớp ItemType để xem ParameterTypes có sẵn cho các AssetTypes khác nhau.

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 Cho phép chúng tôi áp dụng các quy tắc cụ thể hơn nữa cho dữ liệu của chúng tôi, chẳng hạn như danh sách có sẵn Options.

Ví dụ: có thể có một ItemType đại diện cho ParameterType 'loại trường' trên trang web AssetType '.

ItemType này có thể có một danh sách Options đại diện cho các loại trường khác nhau có thể được chọn, chẳng hạn như 'Brownfield' hoặc 'Greenfield'.

Điều này có nghĩa là trong DDB, tất cả các giá trị của 'loại trường' trên 'trang web' sẽ phải là một trong hai tùy chọn đó.

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

Lựa chọn

Một Option là một giá trị có thể được chọn cho Parameter của một ItemType nhất định.

Đây là danh sách đặt trước các giá trị được phép cho các ItemTypes khác nhau.

You can access their values through the 'value' property:

for option in options:
    print(option.value)

Loại đơn vị

DDB có phân loại cho các loại đơn vị.

Ví dụ trong số này bao gồm 'nhiệt độ', 'chiều dài', 'khu vực' và 'âm lượng'.

Chúng cho phép chúng tôi nhóm các đơn vị tương tự nhau, chẳng hạn như 'Celsius' và 'Fahrenheit' cả hai đều thuộc loại đơn vị 'nhiệt độ'.

ParameterTypes có thuộc tính unit_type được sử dụng để hạn chế các đơn vị có thể được sử dụng cho 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```

Bạn cũng có thể truy xuất tất cả các đơn vị cho một `UnitType` đã cho.

```python
my_unit_type = UnitType.get('Length')

length_units = my_unit_unit.get_units()

Hệ thống đơn vị

DDB có một phân loại cho các hệ thống đơn vị.

Ví dụ trong số này bao gồm 'si', 'đế quốc' và 'chung'.

Chúng cho phép chúng tôi phân loại thêm các đơn vị của chúng tôi.

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

Bạn cũng có thể truy xuất tất cả các đơn vị cho một UnitSystem đã cho.

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

### Đơn vị <a id="unit"></a>

DDB có một phân loại cho các đơn vị.

Ví dụ trong số này bao gồm 'm', 'kg' và 'ft'.

```python
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

Loại vai trò

Các loại vai trò xác định các loại quyền truy cập khác nhau vào dự án DDB.

Một người dùng có thể có nhiều vai trò.

The different role types are:

Admin - để sửa đổi quyền của người dùng

Reader - để đọc dữ liệu dự án

Editor - để chỉnh sửa dữ liệu dự án

Checker - để cập nhật trạng thái QA

Approver - để phê duyệt dữ liệu

RoleType là một đối tượng 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]'),
])```

### Nhãn <a id="tag"></a>

`Tags` được sử dụng để tổ chức dữ liệu của chúng tôi và có thể hữu ích cho việc lọc và tìm kiếm.

Ví dụ trong số này bao gồm 'Google', 'Scotland' và 'cơ học'.

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

Loại thẻ

Tags được nhóm lại với nhau bởi TagTypes của họ.

Các ví dụ trong số này bao gồm 'khách hàng', 'khu vực' và 'trạm làm việc'.

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