Python - PyDDB

외부 사용자의 참고 사항 - 다음 섹션의 많은 링크는 내부 응용 프로그램을 나타냅니다. 지원을 위해 프로젝트 팀에 문의하십시오.

pyddb 패키지는 구문을 단순화하고 편의 기능을 구현하여 비 개발자가 DDB와 상호 작용할 수있는 명확한 방법을 제공합니다.

이 안내서는 패키지의 설치 및 빠른 시작, 패키지 및 기능에 대한 전체 참조를 다룹니다.

특징

DDB API 엔드 포인트와 상호 작용하기위한 인터페이스를 크게 단순화하는 것 외에도 라이브러리는 다른 유용한 기능을 제공합니다.

입증

클라이언트는 클라이언트가 인스턴스화되고 필요에 따라 토큰을 자동으로 새로 고침 할 때 사용자에게 ARUP 자격 증명을 요구합니다.

단순화 된 API 및 구현

라이브러리는 자동화 된 워크 플로를 만들려는 초보자 Python 사용자를 위해 구축되었습니다.

우리는 모든 마이크로 서비스 엔드 포인트를 일관된 인터페이스를 가진 단일 라이브러리로 단순화했습니다. 이것은 배우는 것이 적고 시작하기가 쉽다는 것을 의미합니다.

당신은 다시 실행되는 스크립트를 유지할 수 있으며, 복제품을 확인하고 업데이트를 수행 할 것입니다. 일반적으로 스크립트는 프로젝트 번호를 변경하여 다른 프로젝트에서 사용할 수 있습니다.

DDB 분류를 쉽게 탐색하십시오

DDB에는 자체 분류가 있습니다. 새로운 유형의 자산이나 매개 변수 만 만들 수는 없습니다.

이 라이브러리는 기존 분류법을 통해 이름 또는 UUID를 검색하는 방법을 제공합니다.

완전히 테스트되었습니다

이 라이브러리는 현재 및 미래 버전의 DDB API에 대해 완전히 테스트되므로 자신감을 가지고 시작할 수 있습니다.

쪽수 매기기

기본적으로 엔드 포인트는 첫 번째 데이터 페이지를 반환합니다. 이 라이브러리는 페이지 매김을 처리하고 모든 데이터를 검색합니다.

IDE 지원

라이브러리는 완전히 입력되므로 IDE에서 자동 완성 및 유형 확인을받을 수 있습니다.

설치 및 설정

1. Python 3.10+ (App Store)가 필요합니다 - 패키지를 실행하려면 필요합니다.
2. 패키지를 설치하는 데 필요한 git (서비스 데스크)가 필요합니다.
3. 패키지를 설치하는 데 필요한 ARUP 이메일이 포함 된 GitHub 계정이 필요합니다.
4. 권장 Visual Studio Code (App Store) - 코드 작성에 권장되는 환경.

위의 설치가 완료되면 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 \
-i https://ovearup.pkgs.visualstudio.com/_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"),
)

소스 목록을 post_sources 메소드 Project에 전달하여 소스를 DDB에 게시 할 수 있습니다.

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

get_sources에서 Project 메소드를 호출하여 프로젝트의 소스를 다시 리 레트 리 레드 리 레드 리 레드 리 레드 리게 할 수 있습니다.

project_sources = my_project.get_sources()

이것은 과거 프로젝트에서 출처를 얻고 새로운 프로젝트에서 재사용하기가 매우 쉽다는 것을 의미합니다.

유산

Asset 클래스는 자산을 DDB에 생성하고 게시하는 데 사용됩니다. 새 자산은 이름, 자산 유형 및 부모를 create 메소드에 전달하여 인스턴스화됩니다.

주목해야 할 한 가지 중요한 사항은 DDB에서 동일한 이름, 유형 및 부모의 두 자산을 가질 수 없다는 것입니다. 이것은 단일 사이트에 같은 이름의 건물이 2 개를 가질 수 없음을 의미합니다. 이 라이브러리는이 논리를 사용하여 중복 자산이 생성되는 것을 방지하고 대신 스크립트가 다시 실행되면 기존 자산을 반환합니다.

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를 사용할 수 있습니다.

자산 목록을 post_assets 메소드 Project에 전달하여 자산을 DDB에 게시 할 수 있습니다.

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

매개변수는 Project의 post_parameters 메서드에 매개변수 목록을 전달하여 게시할 수 있습니다.

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는 'Brownfield'또는 'Greenfield'와 같이 선택할 수있는 다양한 유형의 필드를 나타내는 Options 목록을 가질 수 있습니다. 이는 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에 대한 모든 장치를 검색 할 수도 있습니다.

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

태그 유형

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