# Python - PyDDB
หมายเหตุสำหรับผู้ใช้ภายนอก - ลิงก์จำนวนมากในส่วนต่อไปนี้อ้างถึงแอปพลิเคชันภายใน กรุณาพูดคุยกับทีมงานโครงการของคุณเพื่อรับการสนับสนุน
แพ็คเกจ
pyddbเป็นวิธีที่ชัดเจนสำหรับผู้ที่ไม่ใช่นักพัฒนาในการโต้ตอบกับ DDB โดยการทำให้ไวยากรณ์ง่ายขึ้นและใช้คุณสมบัติความสะดวกสบาย
คู่มือนี้จะครอบคลุมการติดตั้งและเริ่มต้นอย่างรวดเร็วของแพ็คเกจรวมถึงการอ้างอิงเต็มรูปแบบของแพ็คเกจและคุณสมบัติของมัน
# คุณสมบัติ
Besides greatly simplifying the interface for interacting with the DDB API endpoints, the library provides other useful features:
การรับรองความถูกต้อง
ไคลเอนต์จะแจ้งให้ผู้ใช้สำหรับข้อมูลรับรอง ARUP ของพวกเขาเมื่อไคลเอนต์ถูกสร้างอินสแตนซ์และรีเฟรชโทเค็นโดยอัตโนมัติตามความจำเป็น
API และการใช้งานที่ง่ายขึ้นและการใช้งาน
ห้องสมุดถูกสร้างขึ้นสำหรับผู้ใช้ python ผู้เริ่มต้นที่ต้องการสร้างเวิร์กโฟลว์อัตโนมัติ
เราได้ทำให้จุดสิ้นสุดของ microservice ทั้งหมดง่ายขึ้นในไลบรารีเดียวที่มีอินเตอร์เฟสที่สอดคล้องกัน ซึ่งหมายความว่ามีการเรียนรู้น้อยลงและเริ่มต้นได้ง่าย
คุณสามารถเก็บสคริปต์อีกครั้งและเราจะจัดการการตรวจสอบซ้ำและทำการอัปเดตใด ๆ สำหรับคุณ โดยทั่วไปสคริปต์สามารถใช้กับโครงการอื่น ๆ เพียงแค่เปลี่ยนหมายเลขโครงการ
สำรวจอนุกรมวิธาน DDB ได้อย่างง่ายดาย
DDB has it's own taxonomy: you can't just create a new type of asset or parameter.
This library provides ways of searching through our existing taxonomy by name or uuid.
ทดสอบอย่างเต็มที่
This library is fully tested against current and future versions of the DDB API, so you can get started with confidence.
การปนเปื้อน
โดยค่าเริ่มต้นจุดสิ้นสุดของเราจะส่งคืนหน้าแรกของข้อมูล ไลบรารีนี้จัดการการปนเปื้อนและดึงข้อมูลทั้งหมดให้คุณ
การสนับสนุน IDE
The library is fully typed, so you can get autocomplete and type checking in your IDE.
# Installation and Setup
Requires Python 3.10+ (App Store) - Required to run the package.
ต้องใช้ GIT (แผนกบริการ) - จำเป็นต้องติดตั้งแพ็คเกจ
Requires GitHub account with Arup email - Required to install the package.
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/
Install the PyDDB package
pip install git+https://github.com/arup-group/PyDDB.git
# เริ่มต้นอย่างรวดเร็ว
# Getting Data
การรับข้อมูลจาก DDB นั้นง่ายพอ ๆ กับการเรียกใช้วิธีการที่เหมาะสมในวัตถุโครงการ
สิ่งนี้จะจัดการกับการปนเปื้อนและส่งคืนวัตถุด้วยข้อมูลเมตา มองไปที่ API reference for more information.
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")
# Posting Data
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)
Each of these post methods will return what they are posting and do not add duplicate data. Posting new parameters will not override existing parameters if the value, unit, or source has not changed.
This means that these methods can be used to created automated workflows.
# การอ้างอิง 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:
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.
These classes, such as 'ParameterType' or 'AssetType', are determined by our team. These are ways of categorising our data and giving it context.
กล่าวโดยย่อคลาสข้อมูลเป็นข้อมูลที่คุณทำงานด้วยและคลาสอนุกรมวิธานเป็นวิธีที่เราจำแนก
คุณยังสามารถสำรวจ อภิธานศัพท์ for more information on the terms we use.
# คลาสข้อมูล
ที่ DDB และ Project classes are the main entry points for the library.
The DDB class is used in every script to instantiate the client and set the environment.
The DDB class is used to access data across projects, while the Project class is used to access data on a specific 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
]
)
# Project
The Project class is used to access data on a specific project. It is instantiated by passing the project number to the get_by_number or put methods.
from pyddb import DDB, env, Project
DDB(env.sandbox)
my_project = Project.get_by_number("00000000")
my_project = Project.put("00000000")
The difference between these two methods is that get_by_number will only return the project if it exists in DDB. put will create the project if it does not exist.
# แหล่งที่มา
The Source class is used to create and post sources to DDB. A new source is instantiated by passing the source type, title, and reference to the create method.
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"),
)
แหล่งที่มาสามารถโพสต์ไปยัง DDB โดยส่งรายการแหล่งข้อมูลไปยังวิธี post_sources บน Project
my_project = Project.put("00000000")
my_project.post_sources([my_source])
Sources on a project can be retreived by calling the get_sources method on a Project.
project_sources = my_project.get_sources()
ซึ่งหมายความว่ามันง่ายมากที่จะได้รับแหล่งที่มาจากโครงการที่ผ่านมาและนำกลับมาใช้ใหม่ในโครงการใหม่
# สินทรัพย์
The Asset class is used to create and post assets to DDB. A new asset is instantiated by passing the name, asset type, and parent to the create method.
สิ่งสำคัญอย่างหนึ่งที่ควรทราบคือใน 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,
)
There are a few rules for creating assets:
สินทรัพย์ต้องการ
AssetTypeหรือAssetSubTypeดังนั้นเราจึงรู้ว่ามันคือสินทรัพย์ประเภทใดสินทรัพย์ที่ไม่มี
AssetSubTypeต้องการชื่อสินทรัพย์จำเป็นต้องปฏิบัติตามลำดับชั้นประเภทสินทรัพย์
ตัวอย่างเช่นสินทรัพย์ Building จำเป็นต้องมีสินทรัพย์ Site ในฐานะผู้ปกครอง
คุณสามารถสำรวจคลาส AssetType เพื่อทำความเข้าใจกับลำดับชั้นหรือใช้ DDB UI
สินทรัพย์สามารถโพสต์ไปยัง DDB โดยส่งรายการสินทรัพย์ไปยังวิธี post_assets บน Project
my_project = Project.put("00000000")
my_project.post_assets([my_asset, my_other_asset, yet_another_asset])
Assets on a project can be retreived by calling the get_assets method on a 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,
)
พารามิเตอร์สามารถโพสต์ไปยัง DDB โดยส่งรายการพารามิเตอร์ไปยังวิธี post_parameters บน Project
my_project = Project.put("00000000")
my_project.post_parameters([my_parameter])
A 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 หลายพันคลาสในโครงการของเราและสิ่งเหล่านี้ทั้งหมดถูกจัดประเภทโดยชั้นเรียน taxonomy ParameterType ไม่กี่ชั้น
นี่อาจเป็นหลายร้อยของ Parameter วัตถุที่มี ParameterType ของ "พื้นที่"
คลาสเหล่านี้ใช้เพื่อให้บริบทกับข้อมูลให้โครงสร้างที่สอดคล้องกันและทำให้ง่ายต่อการทำงานด้วย
All of these classes have 3 common methods that you will use to interact with them:
get_all - สิ่งนี้จะส่งคืนวัตถุอนุกรมวิธานทั้งหมดของประเภทนั้นใน DDB
search - สิ่งนี้จะส่งคืนรายการวัตถุอนุกรมวิธานที่ตรงกับคำค้นหา
get - This will return a single taxonomy object by name or uuid.
# Source Type
DDB has a taxonomy for source types.
Examples of these include 'Assumption', 'Derived Value', and 'Industry Guidance'.
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```
### ประเภทสินทรัพย์ <a id="asset-type"></a>
DDB has a taxonomy for asset types.
Examples of these include 'Site', 'Building', 'Space', 'Bridge', 'Tunnel', and 'Road'.
```python
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` ของพวกเขาเพื่อดูว่าพวกเขามีชนิดย่อยหรือไม่
```python
if my_asset_type.asset_sub_type:
sub_types = my_asset_type.get_sub_types()
# ประเภทสินทรัพย์
อนุกรมวิธาน DDB สนับสนุนการจำแนกประเภทสินทรัพย์เพิ่มเติมเป็นประเภทย่อย
เมื่อประเภทสินทรัพย์มีประเภทย่อยอินสแตนซ์ทั้งหมดของประเภทนั้นจะต้องจัดเป็นหนึ่งในประเภทย่อย
ตัวอย่างเช่น 'ระบบอาคาร' AssetType มีหลายประเภทย่อยรวมถึง 'ความร้อน', 'การระบายความร้อน' และ 'แสง'
สินทรัพย์ทั้งหมดของประเภทนี้จะต้องเป็นหนึ่งในประเภทย่อยเหล่านั้น
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```
### Parameter Type <a id="parameter-type"></a>
DDB มีอนุกรมวิธานสำหรับประเภทพารามิเตอร์
ตัวอย่างของสิ่งเหล่านี้รวมถึง 'อุณหภูมิหลอดไฟแห้งในร่มในฤดูร้อน', 'โมดูลัสของความยืดหยุ่น', 'วันที่ตรวจสอบครั้งสุดท้าย'
สิ่งเหล่านี้ใช้ในการจำแนก `Parameters` ของเราและใช้กฎบางอย่างกับพวกเขาเช่นหน่วยที่พวกเขาสามารถมีหรือประเภทข้อมูลที่พวกเขาสามารถเป็นได้
```python
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
# ประเภทรายการ
An ItemType is a combination of an AssetType, a ParameterType, and potentially an 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 allow us to apply even more specific rules to our data, such as a list of available Options.
For example, there could be an ItemType that represents the ParameterType 'Field type' on the AssetType 'Site'.
This ItemType could have a list of Options that represent the different types of fields that can be selected, such as 'Brownfield' or 'Greenfield'.
This would mean that in DDB, all values of 'Field type' on 'Site' assets would have to be one of those two options.
for item_type in site_item_types:
if item_type.has_options:
options = item_type.get_options()
# ตัวเลือก
An Option is a value that can be selected for a Parameter of a certain ItemType.
These are preset lists of values that are allowed for different ItemTypes.
You can access their values through the 'value' property:
for option in options:
print(option.value)
# ประเภทหน่วย
DDB has a taxonomy for unit types.
Examples of these include 'Temperature', 'Length', 'Area', and 'Volume'.
These allow us to group up units that are similar, such as 'Celsius' and 'Fahrenheit' both being in the 'Temperature' unit type.
ParameterTypes have a unit_type property that is used to restrict the units that can be used for that 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` ที่กำหนด
```python
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()```
### หน่วย <a id="unit"></a>
DDB มีอนุกรมวิธานสำหรับหน่วย
ตัวอย่างของสิ่งเหล่านี้รวมถึง 'm', 'kg' และ '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
# ประเภทบทบาท
ประเภทบทบาทกำหนดประเภทของการเข้าถึงโครงการ DDB
ผู้ใช้คนเดียวสามารถมีหลายบทบาท
The different role types are:
Admin - สำหรับการแก้ไขสิทธิ์ของผู้ใช้
Reader - For reading project data
Editor - สำหรับการแก้ไขข้อมูลโครงการ
Checker - For updating QA status
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]'),
])
# Tag
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()