Python - PyDDB

Opmerking voor externe gebruikers - Veel van de links in de volgende sectie verwijzen naar interne toepassingen. Praat alstublieft met uw projectteam voor ondersteuning.

Het pyddb-pakket biedt een duidelijke manier voor niet-ontwikkelaars om met DDB te communiceren door de syntaxis te vereenvoudigen en gemaksfuncties te implementeren.

Deze handleiding omvat de installatie en snel start van het pakket, evenals een volledige referentie van het pakket en de functies ervan.

Functies

Naast het aanzienlijk vereenvoudigen van de interface voor interactie met de DDB API -eindpunten, biedt de bibliotheek andere nuttige functies:

Authenticatie

De client vraagt de gebruiker om zijn Arup -referenties wanneer de client wordt geïnstantieerd en het token automatisch wordt opgespoord indien nodig.

Vereenvoudigde API en implementatie

De bibliotheek is gebouwd voor beginners python gebruikers die geautomatiseerde workflows willen maken.

We hebben alle Microservice -eindpunten vereenvoudigd in een enkele bibliotheek met een consistente interface. Dit betekent dat er minder te leren valt en het is gemakkelijk om aan de slag te gaan.

U kunt de scripts opnieuw uitvoeren en we zullen controleren op duplicaten en het uitvoeren van eventuele updates voor u. Meestal kunnen scripts worden gebruikt op andere projecten alleen door het projectnummer te wijzigen.

Ontdek de DDB -taxonomie gemakkelijk

DDB heeft zijn eigen taxonomie: u kunt niet zomaar een nieuw type activum of parameter maken.

Deze bibliotheek biedt manieren om door onze bestaande taxonomie op naam of UUID te zoeken.

Volledig getest

Deze bibliotheek is volledig getest tegen huidige en toekomstige versies van de DDB API, zodat u met vertrouwen kunt beginnen.

Paginering

Standaard retourneren onze eindpunten de eerste pagina met gegevens. Deze bibliotheek behandelt paginering en haalt alle gegevens voor u op.

IDE -ondersteuning

De bibliotheek is volledig getypt, zodat u autocomplete kunt krijgen en uw IDE kunt controleren.

Installatie en installatie

1. Vereist Python 3.10+ (App Store) - vereist om het pakket uit te voeren.
2. Vereist Git (Service Desk) - Vereist om het pakket te installeren.
3. Vereist GitHub -account bij Arup -e -mail - vereist om het pakket te installeren.
4. Aanbevolen Visual Studio Code (App Store) - Aanbevolen omgeving voor het schrijven van code.

Zodra u het bovenstaande hebt geïnstalleerd, opent u Visual Studio Code en opent u een map waarin u uw werk wilt opslaan.

Open een Bash-terminal en voer de volgende opdrachten uit:

Creëer een virtuele omgeving

python -m venv .venv

Activeer de virtuele omgeving

source .venv/Scripts/activate

Installeer de DDB Python SDK's

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/

Installeer het PyDDB -pakket

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

Snelle start

Gegevens krijgen

Het verkrijgen van gegevens van DDB is net zo eenvoudig als het aanroepen van de juiste methode op het projectobject. Dit zal paginering omgaan en objecten retourneren met metadata. Kijk naar de API -referentie voor meer informatie.

Importeer de delen van de bibliotheek die u nodig heeft:

from pyddb import DDB, env, Project, ParameterType

De klant instantiëren en de omgeving instellen:

ddb = DDB(env.sandbox)

Ontvang een bestaand DDB -project:

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

Krijg gegevens uit het project:

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

Krijg gegevens uit de taxonomie:

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

Gegevens posten

Importeer de delen van de bibliotheek die u nodig heeft:

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

De klant instantiëren en de omgeving instellen:

ddb = DDB(env.sandbox)

Maak een project of krijg een bestaande:

project = Project.put("21515700")

Definieer de activa die u wilt posten:

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

Definieer de parameters die u wilt posten:

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

Plaats de gegevens:

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

Elk van deze postmethoden retourneert wat ze posten en voegt geen dubbele gegevens toe. Het plaatsen van nieuwe parameters zal bestaande parameters niet overschrijven als de waarde, eenheid of bron niet is gewijzigd.

Dit betekent dat deze methoden kunnen worden gebruikt om geautomatiseerde workflows te maken.

API -referentie

Deze documenten worden door de klas afgebroken en bieden een beschrijving en voorbeeld van hoe ze moeten worden gebruikt. In deze bibliotheek hebben we twee hoofdtypen klassen die verschillende doeleinden dienen:

Gegevensklassen : Deze vertegenwoordigen de waarden van onze gegevens en zijn wat u gaat posten en teruggaan om te communiceren met uw projectgegevens. Deze zullen meestal worden gekoppeld aan de taxonomieklassen, dus we weten met wat voor soort gegevens we werken.

Taxonomieklassen : Deze klassen, zoals 'ParameterType' of 'AssetType', worden bepaald door ons team. Dit zijn manieren om onze gegevens te categoriseren en context te geven.

Kortom, de gegevensklassen zijn de gegevens waarmee u werkt en de taxonomieklassen zijn de manieren waarop we het classificeren. U kunt ook onze woordenlijst Voor meer informatie over de voorwaarden die we gebruiken.

Gegevensklassen

De DDB En Project Klassen zijn de belangrijkste toegangspunten voor de bibliotheek. De klasse DDB wordt in elk script gebruikt om de client te instantiëren en de omgeving in te stellen. De klasse DDB wordt gebruikt om toegang te krijgen tot gegevens over projecten, terwijl de Project -klasse wordt gebruikt om toegang te krijgen tot gegevens over een specifiek project.

DDB

De DDB -klasse is de hoofdklasse voor de client. Het wordt gebruikt om de klant te instantiëren en de omgeving in te stellen. Alle scripts moeten de klant instantiëren met de omgeving waarin ze werken.

from pyddb import DDB, env

ddb_client = DDB(env.sandbox)

U kunt dit nu gebruiken om toegang te krijgen tot gegevens over projecten. Het wordt aanbevolen om zeer specifieke vragen te gebruiken om de hoeveelheid geretourneerde gegevens te verminderen.

all_projects = ddb_client.get_projects()

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

Project

De projectklasse wordt gebruikt om toegang te krijgen tot gegevens over een specifiek project. Het wordt geïnstantieerd door het projectnummer door te geven aan de methoden get_by_number of put.

from pyddb import DDB, env, Project

DDB(env.sandbox)

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

Het verschil tussen deze twee methoden is dat get_by_number het project alleen zal retourneren als het bestaat in DDB. put zal het project maken als het niet bestaat.

Bron

De bronklasse wordt gebruikt om bronnen te maken en te plaatsen op DDB. Een nieuwe bron wordt geïnstantieerd door het brontype, de titel en de verwijzing naar de create -methode door te geven.

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

Bronnen kunnen op DDB worden geplaatst door een lijst met bronnen door te geven aan de post_sources -methode op een Project.

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

Bronnen over een project kunnen worden hersteld door de get_sources -methode op een Project te bellen.

project_sources = my_project.get_sources()

Dit betekent dat het heel gemakkelijk is om bronnen uit een vroegere project te krijgen en ze opnieuw te gebruiken in een nieuw project.

Bezit

De Asset -klasse wordt gebruikt om activa te maken en te posten op DDB. Een nieuw actief wordt geïnstantieerd door de naam, het activa -type en de ouder door te geven aan de create -methode.

Een belangrijk ding om op te merken is dat u in DDB niet twee activa kunt hebben met dezelfde naam, type en ouder. Dit betekent dat een enkele site geen twee gebouwen met dezelfde naam kan hebben. Deze bibliotheek gebruikt deze logica om te voorkomen dat er dubbele activa worden gemaakt en zal in plaats daarvan de bestaande activa retourneren als scripts worden herhaald.

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

Er zijn een paar regels voor het maken van activa:

• Activa hebben een AssetType of een AssetSubType nodig, dus we weten wat voor soort activa het is.
• Activa zonder AssetSubType hebben een naam nodig.
• Activa moeten de hiërarchie van het activa -type volgen. Een Building -activum moet bijvoorbeeld een Site -actief als ouder hebben.

U kunt de AssetType -klasse verkennen om inzicht te krijgen in de hiërarchie of de DDB UI te gebruiken.

Activa kunnen op DDB worden geplaatst door een lijst met activa door te geven aan de post_assets -methode op een Project.

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

Activa over een project kunnen worden hersteld door de get_assets -methode op een Project te bellen.

project_assets = my_project.get_assets()

Dit betekent dat het heel gemakkelijk is om activa uit een vroegere project te krijgen en ze opnieuw te gebruiken in een nieuw project.

Parameter

De klasse Parameter wordt gebruikt om parameters te maken en te plaatsen op DDB. Een nieuwe parameter wordt geïnstantieerd door het parametertype, de waarde, eenheid, bron en ouder door te geven aan de create -methode.

U wilt bekend zijn met de klassen Source en Asset voordat u parameters plaatst.

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

Parameters kunnen op DDB worden geplaatst door een lijst met parameters door te geven aan de post_parameters -methode op een Project.

my_project = Project.put("00000000")

my_project.post_parameters([my_parameter])

Een Parameter kan worden gemaakt met slechts een ParameterType, die wanneer gepost, een lege parameter zal maken zonder enige waarden. Wanneer gepost met een waarde, controleert de bibliotheek of de waarde, eenheid of bron is gewijzigd en de parameter bijgewerkt als deze dat heeft gedaan.

We kunnen ook opmerkingen plaatsen naast onze parameters met waarden.

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

Deze klassen vertegenwoordigen de verschillende manieren waarop we onze gegevens hebben geclassificeerd.

Als voorbeeld hebben we duizenden Parameter gegevensklassen in onze projecten, en deze worden allemaal geclassificeerd door enkele ParameterType taxonomieklasse. Dit kunnen honderden Parameter objecten zijn met de ParameterType van "gebied".

Deze klassen worden gebruikt om context aan de gegevens te bieden, deze consistente structuur te geven en het gemakkelijker te maken om mee te werken.

Al deze klassen hebben 3 gemeenschappelijke methoden die u zult gebruiken om ermee te communiceren:

get_all - Dit zal alle taxonomieobjecten van dat type in DDB retourneren.

search - Dit retourneert een lijst met taxonomieobjecten die overeenkomen met de zoekterm.

get - Dit retourneert een enkel taxonomieobject op naam of UUID.

Bron Type

DDB heeft een taxonomie voor brontypen. Voorbeelden hiervan zijn 'veronderstelling', 'afgeleide waarde' en 'industriële richtlijnen'.

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

Type activa

DDB heeft een taxonomie voor activatypen. Voorbeelden hiervan zijn 'Site', 'Building', 'Space', 'Bridge', 'Tunnel' en 'Road'.

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

Sommige activatypen hebben subtypen. U kunt hun asset_sub_type Boolean -eigenschap controleren om te zien of ze subtypen hebben.

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

Activa -subtype

De DDB -taxonomie ondersteunt verdere classificatie van activatypen in subtypen. Wanneer een activatype subtypen heeft, moeten alle instanties van dat type worden geclassificeerd als een van de subtypen.

Als voorbeeld heeft het 'bouwsysteem' AssetType verschillende subtypen, waaronder 'verwarming', 'koeling' en 'verlichting'. Alle activa van dit type moeten een van die subtypen zijn.

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

DDB heeft een taxonomie voor parametertypen. Voorbeelden hiervan zijn 'Summer Indoor Droge lamptemperatuur', 'Modulus van elasticiteit', 'Datum van laatste inspectie'.

Deze worden gebruikt om onze Parameters te classificeren en enkele regels op hen toe te passen, zoals de eenheden die ze kunnen hebben of de gegevenstypen die ze kunnen zijn.

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

Type voorwerp

Een ItemType is een combinatie van een AssetType, A ParameterType en mogelijk een AssetSubType.

Deze worden gemaakt door ons team en maken anders ParameterTypes beschikbaar op verschillende Assets op basis van hun AssetType en AssetSubType. We kunnen de ItemType -klasse gebruiken om te zien welke ParameterTypes beschikbaar zijn voor verschillende 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 Sta ons toe om nog meer specifieke regels toe te passen op onze gegevens, zoals een lijst met beschikbare Options. Er kan bijvoorbeeld een ItemType zijn die het ParameterType 'veldtype' op de site AssetType 'vertegenwoordigt. Deze ItemType kan een lijst hebben van Options die de verschillende soorten velden vertegenwoordigen die kunnen worden geselecteerd, zoals 'Brownfield' of 'Greenfield'. Dit zou betekenen dat in DDB alle waarden van 'veldtype' op 'site' activa een van die twee opties zouden moeten zijn.

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

Keuze

Een Option is een waarde die kan worden geselecteerd voor een Parameter van een bepaalde ItemType. Dit zijn vooraf ingestelde lijsten met waarden die zijn toegestaan voor verschillende ItemTypes.

U hebt toegang tot hun waarden via de eigenschap 'Waarde':

for option in options:
    print(option.value)

Eenheidstype

DDB heeft een taxonomie voor eenheidstypen. Voorbeelden hiervan zijn 'temperatuur', 'lengte', 'gebied' en 'volume'.

Hiermee kunnen we eenheden die vergelijkbaar zijn, zoals 'Celsius' en 'Fahrenheit', beide in het type 'Temperatuur', kunnen groeperen. ParameterTypes hebben een unit_type -eigenschap die wordt gebruikt om de eenheden te beperken die voor die ParameterType kunnen worden gebruikt.

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

U kunt ook alle eenheden ophalen voor een gegeven UnitType.

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

Eenheidssysteem

DDB heeft een taxonomie voor eenheidssystemen. Voorbeelden hiervan zijn 'SI', 'Imperial' en 'General'.

Hiermee kunnen we onze eenheden verder classificeren.

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

U kunt ook alle eenheden ophalen voor een gegeven UnitSystem.

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

Eenheid

DDB heeft een taxonomie voor eenheden. Voorbeelden hiervan zijn 'm', 'kg' en '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

Roltype

Rollentypen definiëren verschillende soorten toegang tot het DDB -project. Een enkele gebruiker kan meerdere rollen hebben.

De verschillende roltypen zijn:

Admin - voor het wijzigen van gebruikersrechten

Reader - voor het lezen van projectgegevens

Editor - voor het bewerken van projectgegevens

Checker - voor het bijwerken van de QA -status

Approver - voor het goedkeuren van gegevens

RoleType is een Enum -object.

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

Label

Tags worden gebruikt om onze gegevens te organiseren en kan nuttig zijn voor filteren en zoeken. Voorbeelden hiervan zijn 'Google', 'Scotland' en '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])

Tagtype

Tags zijn gegroepeerd door hun TagTypes. Voorbeelden hiervan zijn 'klant', 'regio' en 'WorkStage'.

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