Documentazione DDB

# Python - PyDDB

Nota per gli utenti esterni - Molti dei collegamenti nella sezione seguente si riferiscono alle applicazioni interne. Si prega di parlare con il tuo team di progetto per il supporto.

Il pacchetto pyddb fornisce un modo chiaro ai non sviluppatori di interagire con DDB semplificando la sintassi e implementando funzionalità di convenienza.

Questa guida coprirà l'installazione e l'avvio rapido del pacchetto, nonché un riferimento completo del pacchetto e delle sue funzionalità.

# Caratteristiche

Oltre a semplificare notevolmente l'interfaccia per l'interazione con gli endpoint API DDB, la libreria fornisce altre funzionalità utili:

Autenticazione

Il client richiederà all'utente le loro credenziali Arup quando il client viene istanziato e aggiorna automaticamente il token se necessario. Autenticazione

Il client richiederà all'utente le loro credenziali Arup quando il client viene istanziato e aggiorna automaticamente il token se necessario.

Il client richiederà all'utente le loro credenziali Arup quando il client viene istanziato e aggiorna automaticamente il token se necessario.

API semplificata e implementazione

La libreria è creata per gli utenti principianti python che desiderano creare flussi di lavoro automatizzati.

Abbiamo semplificato tutti gli endpoint di microservizio in una singola libreria con un'interfaccia coerente. Ciò significa che c'è meno da imparare ed è facile iniziare.

Puoi continuare gli script di ritrovo e gestiremo il controllo dei duplicati ed eseguire eventuali aggiornamenti per te. In genere gli script possono essere utilizzati su altri progetti semplicemente modificando il numero del progetto.

Esplora facilmente la tassonomia DDB

DDB ha la propria tassonomia: non puoi semplicemente creare un nuovo tipo di risorsa o parametro.

Questa biblioteca fornisce modi di cercare attraverso la nostra tassonomia esistente per nome o UUID.

Completamente testato

Questa biblioteca è completamente testata contro le versioni attuali e future dell'API DDB, quindi puoi iniziare con fiducia.

Impaginazione

Per impostazione predefinita, i nostri endpoint restituiranno la prima pagina di dati. Questa libreria gestisce la impaginazione e recupera tutti i dati per te.

Supporto IDE

La libreria è completamente digitata, quindi è possibile ottenere il completamento automatico e il controllo del tipo nel tuo IDE.

# Installazione e configurazione

  1. Richiede Python 3.10+ (App Store) - richiesto per eseguire il pacchetto.
  2. Richiede Git (service desk) - richiesto per installare il pacchetto.
  3. Richiede l'account GitHub con e -mail Arup - richiesto per installare il pacchetto.
  4. Codice Visual Studio consigliato (App Store) - Ambiente consigliato per il codice di scrittura.

Una volta installato quanto sopra, apri Visual Studio Code e apri una cartella in cui desideri archiviare il tuo lavoro.

Apri un terminale Bash ed esegui i seguenti comandi:

Crea un ambiente virtuale

python -m venv .venv

Attiva l'ambiente virtuale

source .venv/Scripts/activate

Installa gli SDK DDB Python

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/

Installa il pacchetto PyDDB

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

# Avvio rapido

# Ottenere dati

Ottenere dati da DDB è semplice come chiamare il metodo appropriato sull'oggetto del progetto. Ciò gestirà impaginazione e restituirà oggetti con metadati. Guarda al Riferimento API per maggiori informazioni.

Importa le parti della libreria necessarie:

from pyddb import DDB, env, Project, ParameterType

Istanziare il client e impostare l'ambiente:

ddb = DDB(env.sandbox)

Ottieni un progetto DDB esistente:

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

Ottieni dati dal progetto:

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

Ottieni dati dalla tassonomia:

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

# Pubblicare dati

Importa le parti della libreria necessarie:

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

Istanziare il client e impostare l'ambiente:

ddb = DDB(env.sandbox)

Creare un progetto o ottenere uno esistente:

project = Project.put("21515700")

Definisci le risorse che desideri pubblicare:

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

Definisci i parametri che desideri pubblicare:

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

Pubblica i dati:

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

Ognuno di questi metodi post restituirà ciò che stanno pubblicando e non aggiunge dati duplicati. La pubblicazione di nuovi parametri non sovrascriverà i parametri esistenti se il valore, l'unità o l'origine non sono cambiati.

Ciò significa che questi metodi possono essere utilizzati per creare flussi di lavoro automatizzati.

# Riferimento API

Questi documenti sono suddivisi per classe e forniscono una descrizione e un esempio di come dovrebbero essere usati. In questa biblioteca, abbiamo due tipi principali di classi che servono a scopi diversi:

Classi di dati : Questi rappresentano i valori dei nostri dati e sono ciò che pubblicherai e titrefererai per interagire con i dati del progetto. Questi saranno in genere legati alle classi di tassonomia, quindi sappiamo con quale tipo di dati stiamo lavorando.

Classi di tassonomia : Queste classi, come "ParameterType" o "AssetType", sono determinate dal nostro team. Questi sono modi per classificare i nostri dati e dargli un contesto.

In breve, le classi di dati sono i dati con cui stai lavorando e le classi di tassonomia sono il modo in cui li classifichiamo. Puoi anche esplorare il nostro glossario Per ulteriori informazioni sui termini che utilizziamo.

# Classi di dati

La Il Ddb E Progetto Le classi sono i principali punti di iscrizione per la libreria. La classe DDB viene utilizzata in ogni script per istanziare il client e impostare l'ambiente. La classe DDB viene utilizzata per accedere ai dati tra i progetti, mentre la classe Project viene utilizzata per accedere ai dati su un progetto specifico.

# Ddb

La classe DDB è la classe principale per il client. Viene utilizzato per istanziare il client e impostare l'ambiente. Tutti gli script dovrebbero istanziare il cliente con l'ambiente in cui stanno lavorando.

from pyddb import DDB, env

ddb_client = DDB(env.sandbox)

Ora puoi utilizzarlo per accedere ai dati tra i progetti. Si consiglia di utilizzare query molto specifiche per ridurre la quantità di dati restituiti.

all_projects = ddb_client.get_projects()

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

# Progetto

La classe di progetto viene utilizzata per accedere ai dati su un progetto specifico. È istanziato passando il numero del progetto ai metodi get_by_number o put.

from pyddb import DDB, env, Project

DDB(env.sandbox)

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

La differenza tra questi due metodi è che get_by_number restituirà il progetto solo se esiste in DDB. put creerà il progetto se non esiste.

# Fonte

La classe di origine viene utilizzata per creare e pubblicare fonti su DDB. Una nuova fonte è istanziata passando il tipo di sorgente, il titolo e il riferimento al metodo 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"),
)

Le fonti possono essere pubblicate su DDB passando un elenco di fonti al metodo post_sources su un Project.

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

Le fonti di un progetto possono essere ritirate chiamando il metodo get_sources su un Project.

project_sources = my_project.get_sources()

Ciò significa che è molto facile ottenere fonti da un progetto passato e riutilizzarle in un nuovo progetto.

# Risorsa

La classe Asset viene utilizzata per creare e pubblicare risorse su DDB. Una nuova risorsa viene istanziata passando il nome, il tipo di attività e il genitore al metodo create.

Una cosa importante da notare è che in DDB non puoi avere due risorse con lo stesso nome, tipo e genitore. Ciò significa che un singolo sito non può avere due edifici con lo stesso nome. Questa libreria utilizza questa logica per impedire la creazione di risorse duplicate e invece restituirà le risorse esistenti se gli script vengono eseguiti.

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

Ci sono alcune regole per la creazione di risorse:

  • Le attività hanno bisogno di un AssetType o di un AssetSubType, quindi sappiamo che tipo di risorsa è.
  • Le attività senza AssetSubType hanno bisogno di un nome.
  • Le attività devono seguire la gerarchia del tipo di attività. Ad esempio, un'asset Building deve avere un bene Site come genitore.

Puoi esplorare la classe AssetType per comprendere la gerarchia o utilizzare l'interfaccia utente DDB.

Le attività possono essere pubblicate su DDB passando un elenco di attività al metodo post_assets su un Project.

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

Le attività su un progetto possono essere ritirate chiamando il metodo get_assets su un Project.

project_assets = my_project.get_assets()

Ciò significa che è molto facile ottenere risorse da un progetto passato e riutilizzarli in un nuovo progetto.

# Parametro

La classe Parameter viene utilizzata per creare e pubblicare parametri su DDB. Un nuovo parametro viene istanziato passando il tipo di parametro, il valore, l'unità, la sorgente e il genitore al metodo create.

Ti consigliamo di conoscere le classi Source e Asset prima di pubblicare parametri.

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

I parametri possono essere pubblicati su DDB passando un elenco di parametri al metodo post_parameters su un Project.

my_project = Project.put("00000000")

my_project.post_parameters([my_parameter])

Un Parameter può essere creato con solo un ParameterType, che quando pubblicato, creerà un parametro vuoto senza alcun valori. Se pubblicata con un valore, la libreria verificherà se il valore, l'unità o l'origine sono cambiati e aggiornano il parametro se lo è.

Possiamo anche pubblicare commenti insieme ai nostri parametri con valori.

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

# Classi di tassonomia

Queste classi rappresentano i diversi modi in cui abbiamo classificato i nostri dati.

Ad esempio, abbiamo migliaia di classi di dati Parameter nei nostri progetti, e queste sono tutte classificate da alcune lezioni di tassonomia ParameterType. Questo potrebbe essere centinaia di Parameter oggetti con ParameterType di "Area".

Queste classi vengono utilizzate per fornire contesto ai dati, dargli una struttura coerente e rendere più facile lavorare.

Tutte queste classi hanno 3 metodi comuni che utilizzerai per interagire con loro:

get_all - Ciò restituirà tutti gli oggetti di tassonomia di quel tipo in DDB.

search - Ciò restituirà un elenco di oggetti di tassonomia che corrispondono al termine di ricerca.

get - Ciò restituirà un singolo oggetto di tassonomia per nome o UUID.

# Tipo di origine

DDB ha una tassonomia per i tipi di fonti. Esempi di questi includono "Assunzione", "Valore derivato" e "Guida del settore".

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

# Tipo di attività

DDB ha una tassonomia per i tipi di attività. Esempi di questi includono "Sito", "Building", "Space", "Bridge", "Tunnel" e "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

Alcuni tipi di risorse hanno sottotipi. Puoi controllare la loro proprietà booleana asset_sub_type per vedere se hanno sottotipi.

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

# Sottotipo di attività

La tassonomia DDB supporta l'ulteriore classificazione dei tipi di attività in sottomarini. Quando un tipo di risorsa ha sottotitoli, tutte le istanze di quel tipo devono essere classificate come uno dei tipi secondari.

Ad esempio, il "sistema di costruzione" AssetType ha diversi tipi secondari, tra cui "riscaldamento", "raffreddamento" e "illuminazione". Tutte le risorse di questo tipo devono essere uno di quei sottogruppi.

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

# Tipo di parametro

DDB ha una tassonomia per i tipi di parametri. Esempi di questi includono "temperatura estiva di bulbo secco interno", "modulo di elasticità", "data di ultima ispezione".

Questi sono usati per classificare il nostro Parameters e applicare alcune regole ad esse, come le unità che possono avere o i tipi di dati che possono essere.

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

# Tipo di elemento

Un ItemType è una combinazione di AssetType, un ParameterType e potenzialmente un AssetSubType.

Questi sono creati dal nostro team e rendono disponibili diversi ParameterTypes su diversi Assets in base al loro AssetType e AssetSubType. Possiamo usare la classe ItemType per vedere quali ParameterTypes sono disponibili per diversi 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 Permettici di applicare regole ancora più specifiche ai nostri dati, come un elenco di Options disponibile. Ad esempio, potrebbe esserci un ItemType che rappresenta il "tipo di campo" ParameterType sul AssetType "sito". Questo ItemType potrebbe avere un elenco di Options che rappresentano i diversi tipi di campi che possono essere selezionati, come "Brownfield" o "Greenfield". Ciò significherebbe che in DDB tutti i valori di "tipo di campo" sulle risorse "sito" dovrebbero essere una di queste due opzioni.

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

# Opzione

Un Option è un valore che può essere selezionato per un Parameter di un certo ItemType. Questi sono elenchi di valori preimpostati che sono consentiti per diversi ItemTypes.

Puoi accedere ai loro valori tramite la proprietà "Valore":

for option in options:
    print(option.value)

# Tipo di unità

DDB ha una tassonomia per i tipi di unità. Esempi di questi includono "temperatura", "lunghezza", "area" e "volume".

Questi ci consentono di raggruppare unità simili, come "Celsius" e "Fahrenheit" entrambi essendo nel tipo di unità di "temperatura". ParameterTypes hanno una proprietà unit_type che viene utilizzata per limitare le unità che possono essere utilizzate per quella 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

Puoi anche recuperare tutte le unità per un dato UnitType.

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

# Sistema unitario

DDB ha una tassonomia per i sistemi unitari. Esempi di questi includono "Si", "Imperial" e "General".

Questi ci consentono di classificare ulteriormente le nostre unità.

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

Puoi anche recuperare tutte le unità per un dato UnitSystem.

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

# Unità

DDB ha una tassonomia per le unità. Esempi di questi includono "M", "KG" e "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

# Tipo di ruolo

I tipi di ruolo definiscono diversi tipi di accesso al progetto DDB. Un singolo utente può avere più ruoli.

I diversi tipi di ruolo sono:

Admin - Per la modifica delle autorizzazioni utente

Reader - Per la lettura dei dati del progetto

Editor - Per la modifica dei dati del progetto

Checker - Per l'aggiornamento dello stato QA

Approver - Per l'approvazione dei dati

RoleType è un oggetto 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]'),
])

# Etichetta

Tags vengono utilizzati per organizzare i nostri dati e possono essere utili per il filtraggio e la ricerca. Esempi di questi includono "Google", "Scozia" e "Meccanico".

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

# Tipo di tag

Tags sono raggruppati insieme dal loro TagTypes. Esempi di questi includono "client", "regione" e "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()

click me

Last Updated: 13/9/2023, 15:19:15

← Postman →