Python - PyDDB

ملاحظة للمستخدمين الخارجيين - تشير العديد من الروابط في القسم التالي إلى التطبيقات الداخلية. يرجى التحدث إلى فريق المشروع الخاص بك للحصول على الدعم.

توفر حزمة pyddb طريقة واضحة لغير المطورين للتفاعل مع DDB عن طريق تبسيط بناء الجملة وتنفيذ ميزات الراحة.

سيغطي هذا الدليل التثبيت والبدء السريع للحزمة ، بالإضافة إلى مرجع كامل للحزمة وميزاته.

سمات

إلى جانب تبسيط الواجهة بشكل كبير للتفاعل مع نقاط نهاية API DDB ، توفر المكتبة ميزات مفيدة أخرى:

المصادقة

سيطالب العميل بالمستخدم لبيانات اعتماد ARUP الخاصة بهم عندما يتم إنشاء مثيل للعميل وتحديث الرمز المميز تلقائيًا حسب الضرورة.

API المبسط والتنفيذ

تم تصميم المكتبة للمبتدئين Python المستخدمين الذين يرغبون في إنشاء سير عمل آلي.

لقد قمنا بتبسيط جميع نقاط نهاية الخدمات الدقيقة في مكتبة واحدة مع واجهة متسقة. هذا يعني أن هناك أقل للتعلم ومن السهل البدء.

يمكنك الاستمرار في إعادة تشغيل البرامج النصية وسنتعامل مع التحقق من التكرارات وإجراء أي تحديثات لك. عادةً ما يمكن استخدام البرامج النصية في مشاريع أخرى فقط عن طريق تغيير رقم المشروع.

استكشاف تصنيف DDB بسهولة

DDB لديه تصنيف خاص به: لا يمكنك فقط إنشاء نوع جديد من الأصول أو المعلمة.

توفر هذه المكتبة طرقًا للبحث من خلال تصنيفنا الحالي بالاسم أو UUID.

تم اختباره بالكامل

يتم اختبار هذه المكتبة بالكامل مقابل الإصدارات الحالية والمستقبلية من API DDB ، بحيث يمكنك البدء بثقة.

ترقيم الصفحات

بشكل افتراضي ، ستعود نقاط النهاية الخاصة بنا إلى الصفحة الأولى من البيانات. هذه المكتبة تتعامل مع ترقيم الصفحات واسترداد جميع البيانات لك.

دعم IDE

يتم كتابة المكتبة بالكامل ، بحيث يمكنك الحصول على الإكمال التلقائي واكتب التحقق من IDE.

التثبيت والإعداد

1. يتطلب Python 3.10+ (متجر التطبيقات) - مطلوب لتشغيل الحزمة.
2. يتطلب git (مكتب الخدمة) - مطلوب لتثبيت الحزمة.
3. يتطلب حساب GitHub مع Arup البريد الإلكتروني - مطلوب لتثبيت الحزمة.
4. رمز الاستوديو المرئي الموصى به (متجر التطبيق) - بيئة موصى بها لكتابة رمز.

بمجرد تثبيت ما سبق، افتح 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 \
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

يتم تقسيم هذه المستندات حسب الفصل وتقديم وصف ومثال على كيفية استخدامها. في هذه المكتبة ، لدينا نوعان رئيسيان من الفصول التي تخدم أغراض مختلفة:

فئات البيانات : تمثل هذه قيم بياناتنا وهي ما ستنشره وتراجعه للتفاعل مع بيانات المشروع. عادةً ما تكون مرتبطة بفئات التصنيف حتى نعرف نوع البيانات التي نعمل معها.

فئات التصنيف : يتم تحديد هذه الفئات ، مثل "Parametertype" أو "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"),
)

يمكن نشر المصادر على DDB من خلال تمرير قائمة المصادر إلى طريقة post_sources على Project.

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.

يمكن نشر الأصول على DDB عن طريق تمرير قائمة الأصول إلى طريقة post_assets على Project.

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

يمكن نشر المعلمات على DDB عن طريق تمرير قائمة المعلمات إلى طريقة post_parameters على Project.

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 لمعرفة ما إذا كان لديهم أنواع فرعية.

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

نوع المعلمة

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 'نوع الحقل' على AssetType 'الموقع'. يمكن أن يحتوي هذا ItemType على قائمة بـ Options التي تمثل الأنواع المختلفة من الحقول التي يمكن تحديدها ، مثل "Brownfield" أو "Greenfield". هذا يعني أنه في DDB ، يجب أن تكون جميع قيم "نوع الحقل" على موقع "الموقع" واحدة من هذين الخيارين.

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

خيار

Option هي قيمة يمكن تحديدها لـ Parameter من ItemType. هذه قوائم مسبقًا للقيم المسموح بها لمختلف ItemTypes.

يمكنك الوصول إلى قيمها من خلال خاصية "القيمة":

for option in options:
    print(option.value)

نوع الوحدة

DDB لديه تصنيف لأنواع الوحدات. تشمل أمثلة هذه "درجة الحرارة" و "الطول" و "المنطقة" و "الحجم".

هذه تتيح لنا تجميع وحدات متشابهة ، مثل "Celsius" و "Fahrenheit" كلاهما في نوع وحدة "درجة الحرارة". ParameterTypes لها خاصية 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`.

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

وحدة

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" و "اسكتلندا" و "ميكانيكية".

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