Python - PyDDB

Harici kullanıcılar için not - Aşağıdaki bölümdeki bağlantıların çoğu dahili uygulamaları ifade eder. Lütfen destek için proje ekibinizle konuşun.

pyddb paketi, geliştiricilerin sözdizimini basitleştirerek ve kolaylık özelliklerini uygulayarak DDB ile etkileşime girmeleri için net bir yol sağlar.

Bu kılavuz, paketin kurulumunu ve hızlı başlangıcının yanı sıra paketin ve özelliklerinin tam bir referansını kapsayacaktır.

Özellikler

DDB API uç noktaları ile etkileşim kurmak için arayüzü büyük ölçüde basitleştirmenin yanı sıra, kütüphane diğer yararlı özellikler sağlar:

Kimlik doğrulama

İstemci, istemci somutlaştırıldığında ve jetonu otomatik olarak yenilediğinde kullanıcıyı ARUP kimlik bilgileri isteyecektir.

Basitleştirilmiş API ve Uygulama

Kütüphane, otomatik iş akışları oluşturmak isteyen yeni başlayanlar python kullanıcıları için oluşturulmuştur.

Tüm mikro hizmet uç noktalarını tutarlı bir arayüze sahip tek bir kütüphaneye basitleştirdik. Bu, öğrenilecek daha az şey olduğu ve başlaması kolay olduğu anlamına gelir.

Komut dosyalarını tekrar tutabilirsiniz ve kopyaları kontrol etmeyi ve sizin için herhangi bir güncelleme yapmayı gerçekleştireceğiz. Genellikle komut dosyaları diğer projelerde sadece proje numarasını değiştirerek kullanılabilir.

DDB taksonomisini kolayca keşfedin

DDB kendi taksonomisine sahiptir: sadece yeni bir varlık veya parametre türü oluşturamazsınız.

Bu kütüphane, mevcut taksonomimizi ad veya UUID ile arama yolları sağlar.

Tamamen test edilmiş

Bu kütüphane, DDB API'sının mevcut ve gelecekteki sürümlerine karşı tamamen test edilmiştir, böylece güvenle başlayabilirsiniz.

Toplama

Varsayılan olarak, uç noktalarımız verilerin ilk sayfasını döndürür. Bu kütüphane sayfalandırmayı işler ve tüm verileri sizin için alır.

IDE Desteği

Kütüphane tamamen yazılmıştır, böylece IDE'nizde otomatik tamamlama ve tip kontrolü alabilirsiniz.

Kurulum ve Kurulum

1. Paketi çalıştırmak için gerekli Python 3.10+ (App Store) gerektirir.

2. Git (servis masası) gerektirir - paketi yüklemek için gereklidir.

3. ARUP e -posta ile GitHub hesabı gerektirir - paketi yüklemek için gereklidir.

4. Önerilen Visual Studio Kodu (App Store) - Kod yazma için önerilen ortam.

Yukarıdakileri yükledikten sonra Visual Studio Code'u açın ve çalışmanızı depolamak istediğiniz klasörü açın.

Bash terminalini açın ve aşağıdaki komutları çalıştırın:

Sanal bir ortam yaratın

python -m venv .venv

Sanal ortamı etkinleştirin

source .venv/Scripts/activate

DDB Python SDK'ları yükleyin

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/

PyDDB paketini yükleyin

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

Hızlı başlangıç

Veri almak

DDB'den veri almak, proje nesnesindeki uygun yöntemi çağırmak kadar basittir.

Bu, meta verilerle sayfalandırma ve nesneleri döndürür. Bak API referansı daha fazla bilgi için.

İhtiyacınız olan kütüphanenin parçalarını içe aktarın:

from pyddb import DDB, env, Project, ParameterType

Müşteriyi somutlaştırın ve ortamı belirleyin:

ddb = DDB(env.sandbox)

Mevcut bir DDB projesi alın:

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

Projeden veri alın:

project_parameters = my_project.get_parameters()

project_assets = my_project.get_assets()

project_sources = my_project.get_sources()

Taksonomiden veri alın:

all_parameter_types = ParameterType.get_all()

some_parameter_types = ParameterType.search('area')

my_parameter_type = ParameterType.get("Plot area")

Verileri Gönderme

İhtiyacınız olan kütüphanenin parçalarını içe aktarın:

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

Müşteriyi somutlaştırın ve ortamı belirleyin:

ddb = DDB(env.sandbox)

Bir proje oluşturun veya mevcut bir proje alın:

project = Project.put("21515700")

Göndermek istediğiniz varlıkları tanımlayın:

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

Göndermek istediğiniz parametreleri tanımlayın:

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

Verileri gönderin:

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

Bu posta yöntemlerinin her biri yayınladıkları şeyi döndürür ve yinelenen veri eklemez. Değer, birim veya kaynak değişmediyse, yeni parametrelerin yayınlanması mevcut parametreleri geçersiz kılmaz.

Bu, bu yöntemlerin otomatik iş akışları oluşturmak için kullanılabileceği anlamına gelir.

API referansı

Bu dokümanlar sınıfa göre parçalanır ve nasıl kullanılması gerektiğine dair bir açıklama ve örnek sağlar.

Bu kütüphanede, farklı amaçlara hizmet eden iki ana sınıf türümüz var:

Veri Sınıfları :

Bunlar verilerimizin değerlerini temsil eder ve proje verilerinizle etkileşim kurmak için yayınlayacağınız ve geri çekeceğiniz şeydir.

Bunlar genellikle taksonomi sınıflarına bağlı olacaktır, böylece ne tür verilerle çalıştığımızı biliyoruz.

Taksonomi sınıfları :

'Parametreype' veya 'AssetType' gibi bu sınıflar ekibimiz tarafından belirlenir. Bunlar verilerimizi sınıflandırmanın ve bağlam vermenin yollarıdır.

Kısacası, veri sınıfları birlikte çalıştığınız verilerdir ve taksonomi sınıfları onu sınıflandırmamızdır.

Ayrıca keşfedebilirsiniz sözlük Kullandığımız terimler hakkında daha fazla bilgi için.

Veri Sınıfları

. DDB Ve Proje Sınıflar kütüphane için ana giriş noktalarıdır.

DDB sınıfı her komut dosyasında istemciyi somutlaştırmak ve çevreyi ayarlamak için kullanılır.

DDB sınıfı, projeler arasında verilere erişmek için kullanılırken, Project sınıfı belirli bir projedeki verilere erişmek için kullanılır.

DDB

DDB sınıfı müşteri için ana sınıftır. Müşteriyi somutlaştırmak ve çevreyi ayarlamak için kullanılır. Tüm komut dosyaları, müşteriyi çalıştıkları ortamla başlatmalıdır.

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

Şimdi bunu projeler arasında verilere erişmek için kullanabilirsiniz.

İade edilen veri miktarını azaltmak için çok özel sorguların kullanılması önerilir.

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

Proje

Proje sınıfı, belirli bir projedeki verilere erişmek için kullanılır. Proje numarasını get_by_number veya put yöntemlerine geçirerek başlatılır.

from pyddb import DDB, env, Project
DDB(env.sandbox)
my_project = Project.get_by_number("00000000")
my_project = Project.put("00000000")

Bu iki yöntem arasındaki fark, get_by_number'ın projeyi yalnızca DDB'de varsa döndürmesidir. put mevcut değilse projeyi oluşturacaktır.

Kaynak

Kaynak sınıfı DDB'ye kaynak oluşturmak ve yayınlamak için kullanılır. Yeni bir kaynak, kaynak türünü, başlığını ve create yöntemine atıfta bulunarak somutlaştırılır.

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

Kaynaklar, post_sources üzerindeki Project yöntemine bir kaynak listesi geçirerek DDB'ye gönderilebilir.

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

Bir projedeki kaynaklar get_sources yöntemini Project üzerinden çağırarak geri alınabilir.

project_sources = my_project.get_sources()

Bu, geçmiş bir projeden kaynak almanın ve onları yeni bir projede yeniden kullanmanın çok kolay olduğu anlamına gelir.

Varlık

Asset sınıfı, DDB'ye varlık oluşturmak ve yayınlamak için kullanılır. Yeni bir varlık, ad, varlık türü ve ebeveyni create yöntemine aktararak başlatılır.

Dikkat edilmesi gereken önemli bir şey, DDB'de aynı ad, tip ve ebeveyn olan iki varlığa sahip olamayacağıdır. Bu, tek bir sitenin aynı adı taşıyan iki binaya sahip olamayacağı anlamına gelir.

Bu kütüphane, bu mantığı yinelenen varlıkların oluşturulmasını önlemek için kullanır ve bunun yerine komut dosyaları yeniden çalıştırılırsa mevcut varlıkları iade edecektir.

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

Varlıklar oluşturmak için birkaç kural vardır:

• Varlıkların bir AssetType veya AssetSubType olması gerekir, böylece ne tür bir varlık olduğunu biliyoruz.

• AssetSubType olmayan varlıkların bir isme ihtiyacı vardır.

• Varlıkların varlık türü hiyerarşisini takip etmesi gerekir.

Örneğin, bir Building varlığının ebeveyn olarak Site varlığına sahip olması gerekir.

Hiyerarşiyi anlamak veya DDB kullanıcı arayüzünü kullanmak için AssetType sınıfını keşfedebilirsiniz.

Varlıklar, post_assets yöntemine Project yöntemine bir varlık listesi aktararak DDB'ye gönderilebilir.

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

Bir projedeki varlıklar get_assets yöntemini Project'da çağırarak yeniden tasarlanabilir.

project_assets = my_project.get_assets()

Bu, geçmiş bir projeden varlık almanın ve onları yeni bir projede yeniden kullanmanın çok kolay olduğu anlamına gelir.

Parametre

Parameter sınıfı DDB'ye parametreler oluşturmak ve yayınlamak için kullanılır. Yeni bir parametre, parametre türü, değer, birim, kaynak ve parametre create yöntemine aktarılarak başlatılır. Parametreleri yayınlamadan önce Source ve Asset sınıflarına aşina olmak isteyeceksiniz.

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

Parametreler, post_parameters üzerindeki Project yöntemine bir parametre listesi iletilerek DDB'ye gönderilebilir.

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

A Parameter, yayınlandığında herhangi bir değer olmadan boş bir parametre oluşturacak olan sadece bir ParameterType ile oluşturulabilir.

Bir değerle gönderildiğinde, kütüphane değerin, birimin veya kaynağın değişip değişmediğini kontrol eder ve parametreyi varsa günceller.

Ayrıca değerlerle parametrelerimizin yanında yorum gönderebiliriz.

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

Taksonomi sınıfları

Bu sınıflar, verilerimizi sınıflandırdığımız farklı yolları temsil eder.

Örnek olarak, projelerimizde binlerce Parameter veri sınıfımız var ve bunların hepsi birkaç ParameterType taksonomi sınıfı ile sınıflandırılıyor.

Bu, Parameter "Alan" ile yüzlerce ParameterType nesnesi olabilir.

Bu sınıflar verilere bağlam sağlamak, tutarlı bir yapı sağlamak ve çalışmayı kolaylaştırmak için kullanılır.

Bu sınıfların hepsinin onlarla etkileşim kurmak için kullanacağınız 3 ortak yöntemi vardır:

get_all - Bu, DDB'deki bu türdeki tüm taksonomi nesnelerini döndürür.

search - Bu, arama terimine uygun taksonomi nesnelerinin bir listesini döndürür.

get - Bu, ad veya UUID ile tek bir taksonomi nesnesini döndürür.

kaynak tipi

DDB'nin kaynak türleri için bir taksonomi vardır.

Bunlara örnek olarak 'varsayım', 'türetilmiş değer' ve 'endüstri rehberliği' yer alır.

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

Varlık türü

DDB'nin varlık türleri için bir taksonomi vardır.

Bunlara örnek olarak 'site', 'bina', 'uzay', 'köprü', 'tünel' ve 'yol' bulunur.

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

Bazı varlık türlerinin alt tipleri vardır. Alt tipleri olup olmadığını görmek için asset_sub_type boolean özelliklerini kontrol edebilirsiniz.

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

Varlık alt tipi

DDB taksonomisi, varlık türlerinin alt türlere daha fazla sınıflandırılmasını destekler.

Bir varlık türünün alt türleri olduğunda, bu türün tüm örnekleri alt türlerden biri olarak sınıflandırılmalıdır.

Örnek olarak, 'bina sistemi' AssetType, 'ısıtma', 'soğutma' ve 'aydınlatma' dahil olmak üzere birkaç alt türe sahiptir.

Bu tür tüm varlıkların bu alt türlerden biri olması gerekir.

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

Parametre türü

DDB'nin parametre türleri için bir taksonomi vardır.

Bunların örnekleri arasında 'yaz iç mekan kuru ampul sıcaklığı', 'esneklik modülü', 'Son İnceleme Tarihi'.

Bunlar Parameters'ımızı sınıflandırmak ve sahip olabilecekleri birimler veya olabilecekleri veri türleri gibi bazı kuralları uygulamak için kullanılır.

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

Öğe türü

ItemType, AssetType, bir ParameterType ve potansiyel olarak AssetSubType'ın bir kombinasyonudur.

Bunlar ekibimiz tarafından oluşturulur ve ParameterTypes ve Assets'larına göre farklı AssetType'da farklı AssetSubType sunar.

Farklı ItemType için hangi ParameterTypes'ın mevcut olduğunu görmek için AssetTypes sınıfını kullanabiliriz.

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 Mevcut Options listesi gibi verilerimize daha spesifik kurallar uygulamamıza izin verin.

Örneğin, ItemType 'sitesinde' ParameterType 'alan türünü' temsil eden bir AssetType olabilir.

Bu ItemType, 'Brownfield' veya 'Greenfield' gibi seçilebilen farklı alan türlerini temsil eden Options listesine sahip olabilir.

Bu, DDB'de, 'site' varlıklarındaki tüm 'alan türü' değerlerinin bu iki seçenekten biri olması gerektiği anlamına gelir.

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

Seçenek

Option, belirli bir Parameter ItemType için seçilebilen bir değerdir.

Bunlar, farklı ItemTypes için izin verilen değerlerin önceden ayarlanmış listeleridir.

Değerlerine 'değer' özelliği aracılığıyla erişebilirsiniz:

for option in options:
    print(option.value)

Birim tipi

DDB, birim türleri için bir taksonomiye sahiptir.

Bunlara örnek olarak 'sıcaklık', 'uzunluk', 'alan' ve 'hacim' bulunur.

Bunlar, her ikisi de 'Sıcaklık' birim tipinde 'Santigrat' ve 'Fahrenheit' gibi benzer birimleri gruplamamıza izin verir.

ParameterTypes, unit_type için kullanılabilecek birimleri kısıtlamak için kullanılan bir ParameterType özelliğine sahiptir.

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

Belirli bir UnitType için tüm birimleri de alabilirsiniz.

my_unit_type = UnitType.get('Length')

length_units = my_unit_unit.get_units()

Birim sistemi

DDB, birim sistemleri için bir sınıflandırmaya sahiptir.

Bunlara örnek olarak 'Si', 'İmparatorluk' ve 'Genel' yer alır.

Bunlar birimlerimizi daha da sınıflandırmamıza izin verir.

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

Belirli bir UnitSystem için tüm birimleri de alabilirsiniz.

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

Birim

DDB'nin birimler için bir taksonomi vardır.

Bunların örnekleri arasında 'M', 'kg' ve 'ft' bulunur.

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

Rol Türü

Rol türleri DDB projesine farklı erişim türlerini tanımlar.

Tek bir kullanıcının birden fazla rolü olabilir.

Farklı rol türleri:

Admin - Kullanıcı izinlerini değiştirmek için

Reader - Proje verilerini okumak için

Editor - Proje verilerini düzenlemek için

Checker - KG durumunu güncellemek için

Approver - Verileri onaylamak için

RoleType bir Enum nesnesidir.

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

Etiket

Tags verilerimizi düzenlemek için kullanılır ve filtreleme ve arama için yararlı olabilir.

Bunlara örnek olarak 'Google', 'İskoçya' ve 'Mekanik' yer alıyor.

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

Etiket Türü

Tags TagTypes ile birlikte gruplandırılır.

Bunlara örnek olarak 'Müşteri', 'Bölge' ve 'WorkStage' bulunur.

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