Python - PyDDB

Hinweis für externe Benutzer - Viele der Links im folgenden Abschnitt beziehen sich auf interne Anwendungen. Bitte sprechen Sie mit Ihrem Projektteam zur Unterstützung.

Das pyddb-Paket bietet Nichtentwicklern eine klare Möglichkeit, mit DDB zu interagieren, indem Syntax vereinfacht und Convenience-Funktionen implementiert werden.

Diese Anleitung umfasst die Installation und den schnellen Start des Pakets sowie eine vollständige Referenz des Pakets und seiner Funktionen.

Merkmale

Die Bibliothek ist nicht nur die Schnittstelle für die Interaktion mit den DDB -API -Endpunkten für die Interaktion mit den DDB -API -Endpunkten erheblich zu vereinfachen:

Authentifizierung

Der Client fordert den Benutzer für seine ARUP -Anmeldeinformationen auf, wenn der Client instanziiert wird, und aktualisiert das Token nach Bedarf automatisch.

Vereinfachte API und Implementierung

Die Bibliothek ist für Anfänger python Benutzer erstellt, die automatisierte Workflows erstellen möchten.

Wir haben alle Microservice -Endpunkte in einer einzigen Bibliothek mit einer konsistenten Schnittstelle vereinfacht. Dies bedeutet, dass es weniger zu lernen gibt und es ist einfach, loszulegen.

Sie können die Skripte weitergeben und wir werden es überprüft, um Duplikate zu überprüfen und Updates für Sie durchzuführen. Normalerweise können Skripte für andere Projekte verwendet werden, indem die Projektnummer geändert wird.

Die DDB -Taxonomie problemlos erkunden

DDB hat seine eigene Taxonomie: Sie können nicht einfach eine neue Art von Vermögenswert oder Parameter erstellen.

Diese Bibliothek bietet Möglichkeiten, unsere bestehende Taxonomie nach Namen oder UUID zu suchen.

Vollständig getestet

Diese Bibliothek wird vollständig gegen aktuelle und zukünftige Versionen der DDB -API getestet, sodass Sie mit Zuversicht beginnen können.

Seitennummerierung

Standardmäßig gibt unsere Endpunkte die erste Datenseite zurück. Diese Bibliothek kümmert sich um Paginierung und holt alle Daten für Sie ab.

IDE -Unterstützung

Die Bibliothek ist vollständig eingegeben, sodass Sie automatisch vervollständigt und die Überprüfung in Ihrer IDE eingeben können.

Installation und Setup

1. Benötigt Python 3.10+ (App Store) - erforderlich, um das Paket auszuführen.
2. Benötigt GIT (Service Desk) - erforderlich, um das Paket zu installieren.
3. Erfordert GitHub -Konto mit Arup -E -Mail - erforderlich, um das Paket zu installieren.
4. Empfohlener Visual Studio Code (App Store) - Empfohlene Umgebung zum Schreiben von Code.

Sobald Sie das oben genannte installiert haben, öffnen Sie Visual Studio Code und öffnen Sie einen Ordner, in dem Sie Ihre Arbeit speichern möchten.

Öffnen Sie ein Bash-Terminal und führen Sie die folgenden Befehle aus:

Erstellen Sie eine virtuelle Umgebung

python -m venv .venv

Aktivieren Sie die virtuelle Umgebung

source .venv/Scripts/activate

Installieren Sie die 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/

Installieren Sie das PyDDB -Paket

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

Schnellstart

Daten erhalten

Das Erhalten von Daten von DDB ist so einfach wie das Aufrufen der entsprechenden Methode für das Projektobjekt. Dadurch werden Paginierung und Rückgabelegungen mit Metadaten behandelt. Schaue auf die API -Referenz für mehr Informationen.

Importieren Sie die Teile der Bibliothek, die Sie benötigen:

from pyddb import DDB, env, Project, ParameterType

Sofortieren Sie den Kunden und setzen Sie die Umgebung:

ddb = DDB(env.sandbox)

Holen Sie sich ein vorhandenes DDB -Projekt:

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

Holen Sie sich Daten aus dem Projekt:

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

Erhalten Sie Daten aus der Taxonomie:

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

Daten veröffentlichen

Importieren Sie die Teile der Bibliothek, die Sie benötigen:

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

Sofortieren Sie den Kunden und setzen Sie die Umgebung:

ddb = DDB(env.sandbox)

Erstellen Sie ein Projekt oder erhalten Sie ein vorhandenes:

project = Project.put("21515700")

Definieren Sie die Vermögenswerte, die Sie posten möchten:

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

Definieren Sie die Parameter, die Sie posten möchten:

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

Veröffentlichen Sie die Daten:

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

Jede dieser Post -Methoden gibt zurück, was sie veröffentlichen, und fügen keine doppelten Daten hinzu. Durch das Posten neuer Parameter werden vorhandene Parameter nicht überschrieben, wenn sich der Wert, die Einheit oder die Quelle nicht geändert haben.

Dies bedeutet, dass diese Methoden verwendet werden können, um automatisierte Workflows zu erstellen.

API -Referenz

Diese Dokumente werden vom Unterricht unterteilt und geben eine Beschreibung und ein Beispiel dafür, wie sie verwendet werden sollten. In dieser Bibliothek haben wir zwei Hauptstypen von Klassen, die unterschiedliche Zwecke dienen:

Datenklassen : Diese repräsentieren die Werte unserer Daten und sind das, was Sie veröffentlichen und im Ruhestand veröffentlichen werden, um mit Ihren Projektdaten zu interagieren. Diese werden in der Regel an die Taxonomieklassen gebunden, sodass wir wissen, mit welchen Daten wir arbeiten.

Taxonomieklassen : Diese Klassen wie "ParameterType" oder "Assettype" werden von unserem Team bestimmt. Dies sind Möglichkeiten, unsere Daten zu kategorisieren und ihnen einen Kontext zu geben.

Kurz gesagt, die Datenklassen sind die Daten, mit denen Sie arbeiten, und die Taxonomieklassen sind die Art und Weise, wie wir sie klassifizieren. Sie können auch unsere erkunden Glossar Weitere Informationen zu den von uns verwendeten Begriffen.

Datenklassen

Der DDB Und Projekt Klassen sind die Haupteintrittspunkte für die Bibliothek. Die DDB -Klasse wird in jedem Skript verwendet, um den Client zu instanziieren und die Umgebung festzulegen. Die DDB -Klasse wird verwendet, um über Projekte hinweg auf Daten zuzugreifen, während die Project -Klasse zum Zugriff auf Daten zu einem bestimmten Projekt verwendet wird.

DDB

Die DDB -Klasse ist die Hauptklasse für den Kunden. Es wird verwendet, um den Kunden zu instanziieren und die Umgebung festzulegen. Alle Skripte sollten den Kunden mit der Umgebung instanziieren, in der er arbeitet.

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

Sie können dies jetzt verwenden, um über Projekte hinweg auf Daten zuzugreifen. Es wird empfohlen, sehr bestimmte Fragen zu verwenden, um die zurückgegebene Datenmenge zu verringern.

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

Projekt

Die Projektklasse wird verwendet, um auf Daten zu einem bestimmten Projekt zuzugreifen. Es wird instanziiert, indem die Projektnummer an die Methoden get_by_number oder put weitergeleitet wird.

from pyddb import DDB, env, Project

DDB(env.sandbox)

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

Der Unterschied zwischen diesen beiden Methoden besteht darin, dass get_by_number das Projekt nur dann zurückgibt, wenn es in DDB vorliegt. put erstellt das Projekt, wenn es nicht existiert.

Quelle

Die Quellklasse wird verwendet, um Quellen für DDB zu erstellen und nachzubilden. Eine neue Quelle wird instanziiert, indem der Quellentyp, den Titel und den Verweis auf die create -Methode übergeben wird.

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

Quellen können an DDB veröffentlicht werden, indem eine Liste von Quellen an die post_sources -Methode auf Project weitergeleitet wird.

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

Quellen für ein Projekt können durch den Aufruf der get_sources -Methode auf Project reträumiert werden.

project_sources = my_project.get_sources()

Dies bedeutet, dass es sehr einfach ist, Quellen aus einem früheren Projekt zu erhalten und sie in einem neuen Projekt wiederzuverwenden.

Anlage

Die Asset -Klasse wird verwendet, um Assets für DDB zu erstellen und nachzubilden. Ein neues Vermögenswert wird durch Übergabe des Namens, des Vermögens Typ und der Eltern an die create -Methode instanziiert.

Eine wichtige Sache zu beachten ist, dass Sie in DDB nicht zwei Vermögenswerte mit demselben Namen, dem Typ und demselben übergeordneten haben können. Dies bedeutet, dass eine einzelne Site nicht zwei Gebäude mit demselben Namen haben können. Diese Bibliothek verwendet diese Logik, um zu verhindern, dass doppelte Vermögenswerte erstellt werden, und gibt stattdessen die vorhandenen Vermögenswerte zurück, wenn Skripte wiederholt werden.

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

Es gibt einige Regeln für das Erstellen von Vermögenswerten:

• Vermögenswerte benötigen entweder AssetType oder AssetSubType, sodass wir wissen, welche Art von Vermögen es ist.
• Vermögenswerte ohne AssetSubType brauchen einen Namen.
• Vermögenswerte müssen der Hierarchie der Vermögensart folgen. Zum Beispiel muss ein Building -Vermögenswert als Elternteil einen Site -Vermögenswert haben.

Sie können die AssetType -Klasse untersuchen, um die Hierarchie zu verstehen oder die DDB -Benutzeroberfläche zu verwenden.

Vermögenswerte können an DDB veröffentlicht werden, indem eine Liste mit Vermögenswerten an die post_assets -Methode auf Project weitergegeben wird.

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

Vermögenswerte für ein Projekt können durch den Aufruf der get_assets -Methode auf Project reträumiert werden.

project_assets = my_project.get_assets()

Dies bedeutet, dass es sehr einfach ist, Vermögenswerte aus einem früheren Projekt zu erhalten und sie in einem neuen Projekt wiederzuverwenden.

Parameter

Die Parameter -Klasse wird verwendet, um Parameter für DDB zu erstellen und zu postieren. Ein neuer Parameter wird instanziiert, indem der Parametertyp, den Wert, die Einheit, die Quelle und den Elternteil an die create -Methode weitergegeben werden.

Sie möchten mit den Klassen Source und Asset vertraut sein, bevor Sie Parameter veröffentlichen.

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

Parameter können an DDB veröffentlicht werden, indem eine Liste von Parametern an die post_parameters -Methode auf einem Project übergeben wird.

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

A Parameter kann mit nur einem ParameterType erstellt werden, der nach dem Veröffentlichung einen leeren Parameter ohne Werte erstellt. Wenn die Bibliothek mit einem Wert veröffentlicht wird, prüft sie, ob sich der Wert, die Einheit oder die Quelle geändert haben, und aktualisieren Sie den Parameter.

Wir können auch Kommentare neben unseren Parametern mit Werten veröffentlichen.

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

Taxonomieklassen

Diese Klassen repräsentieren die unterschiedlichen Möglichkeiten, wie wir unsere Daten klassifiziert haben.

Als Beispiel haben wir Tausende von Parameter Datenklassen in unseren Projekten, die alle nach einigen ParameterType Taxonomieklassen klassifiziert werden. Dies könnten Hunderte von Parameter -Objekten mit dem ParameterType "Bereich" sein.

Diese Klassen werden verwendet, um den Daten einen Kontext bereitzustellen, ihm eine konsistente Struktur zu geben und die Arbeit zu erleichtern.

Alle diese Klassen haben 3 gemeinsame Methoden, mit denen Sie mit ihnen interagieren:

get_all - Dies gibt alle Taxonomieobjekte dieser Art in DDB zurück.

search - Dies gibt eine Liste von Taxonomieobjekten zurück, die dem Suchbegriff entsprechen.

get - Dies gibt ein einzelnes Taxonomie -Objekt per Namen oder UUID zurück.

Quelle Typ

DDB hat eine Taxonomie für Quellentypen. Beispiele hierfür sind "Annahme", "abgeleiteter Wert" und "Branchenführung".

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

Asset -Typ

DDB hat eine Taxonomie für Vermögenstypen. Beispiele hierfür sind "Standort", "Gebäude", "Raum", "Brücke", "Tunnel" und "Straße".

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

Einige Vermögenstypen haben Subtypen. Sie können ihre asset_sub_type booleale Eigenschaft überprüfen, um festzustellen, ob sie Subtypen haben.

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

Asset Subtyp

Die DDB -Taxonomie unterstützt die weitere Klassifizierung von Vermögenstypen in Untertypen. Wenn ein Asset -Typ Subyptypen hat, müssen alle Instanzen dieses Typs als einer der Sub -Typen klassifiziert werden.

Als Beispiel hat das 'Gebäudesystem' AssetType mehrere Untertypen, einschließlich 'Heizung', 'Kühlung' und 'Beleuchtung'. Alle Vermögenswerte dieser Art müssen einer dieser Untertypen sein.

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

Parametertyp

DDB hat eine Taxonomie für Parametertypen. Beispiele hierfür sind "Sommer in der Trockenbirne in der Innenräumung", "Elastizitätsmodul", "Datum der letzten Inspektion".

Diese werden verwendet, um unsere Parameters zu klassifizieren und einige Regeln auf sie anzuwenden, z. B. die Einheiten, die sie haben können, oder die Datentypen, die sie sein können.

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

Gegenstandsart

Ein ItemType ist eine Kombination aus AssetType, A ParameterType und möglicherweise ein AssetSubType.

Diese werden von unserem Team erstellt und machen unterschiedliche ParameterTypes für verschiedene Assets, basierend auf ihren AssetType und AssetSubType verfügbar. Wir können die ItemType -Klasse verwenden, um zu sehen, welche ParameterTypes für verschiedene AssetTypes verfügbar sind.

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 Ermöglichen Sie uns, noch spezifischere Regeln auf unsere Daten anzuwenden, z. B. eine Liste der verfügbaren Options. Zum Beispiel könnte es einen ItemType geben, der den Feld ParameterType auf der AssetType 'Site' darstellt. Dieser ItemType könnte eine Liste von Options haben, die die verschiedenen Arten von Feldern darstellen, die ausgewählt werden können, wie z. B. "Brownfield" oder "Greenfield". Dies würde bedeuten, dass in DDB alle Werte des "Feldtyps" auf "Site" -Argument eine dieser beiden Optionen sein müssten.

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

Möglichkeit

Ein Option ist ein Wert, der für einen Parameter eines bestimmten ItemType ausgewählt werden kann. Dies sind voreingestellte Wertelisten, die für unterschiedliche ItemTypes zulässig sind.

Sie können über die Eigenschaft "Wert" auf ihre Werte zugreifen:

for option in options:
    print(option.value)

Gerätetyp

DDB hat eine Taxonomie für Einheitstypen. Beispiele hierfür sind "Temperatur", "Länge", "Fläche" und "Volumen".

Diese ermöglichen es uns, Einheiten zu gruppieren, die ähnlich sind, wie z. ParameterTypes eine unit_type Eigenschaft, mit der die Einheiten eingehalten werden, die für ParameterType verwendet werden können.

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

Sie können auch alle Einheiten für einen bestimmten `UnitType` abrufen.

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

Einheitssystem

DDB hat eine Taxonomie für Einheitssysteme. Beispiele hierfür sind 'si', 'imperial' und 'allgemein'.

Diese ermöglichen es uns, unsere Einheiten weiter zu klassifizieren.

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

Sie können auch alle Einheiten für einen bestimmten UnitSystem abrufen.

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

Einheit

DDB hat eine Taxonomie für Einheiten. Beispiele hierfür sind 'M', 'KG' und '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

Rollentyp

Rollentypen definieren verschiedene Arten von Zugriff auf das DDB -Projekt. Ein einzelner Benutzer kann mehrere Rollen spielen.

Die verschiedenen Rollentypen sind:

Admin - zur Änderung der Benutzerberechtigungen

Reader - zum Lesen von Projektdaten

Editor - zum Bearbeiten von Projektdaten

Checker - zum Aktualisieren des QA -Status

Approver - zur Genehmigung von Daten

RoleType ist ein Enum -Objekt.

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

Schild

Tags werden verwendet, um unsere Daten zu organisieren und kann zum Filtern und Suchen nützlich sein. Beispiele hierfür sind "Google", "Schottland" und "mechanisch".

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

Tag -Typ

Tags werden von ihrem TagTypes zusammen gruppiert. Beispiele hierfür sind "Kunde", "Region" und "Work Bühne".

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