Package: adttools
adttoolsSystem RequirementPython 3.6 or abovepandasTable of contentsModelHelperlist_modelsfind_model_components_listpickerget_component_dictRelationshipHelperlist_relationshipsadd_relationshipdelete_relationshipfind_relationships_with_targetfind_and_delete_relationshipsPropertyHelperget_twin_detailprepare_propertyprepare_componentprepare_relationshipsubmitupdate_propertyadd_propertyremove_propertyTwinHelperadd_twindelete_twinQueryHelperquery_twinsquery_relationshipsrun_queryDeployHelpercsv_deployclearadttools.helperAll helpers requires 3 parameters to initialize. Eithertoken_pathortokenshould be given.host_name:strHost name of the Azure Digital Twins Instance. You can get it from the Azure portal.token_path:strThe path of a text file storing the bearer token get by using this command with Azure CLI.az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0token:strA string of token. Get by using this command with Azure CLI.az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0adttools.helper.ModelHelperclass adttools.helper.ModelHelper(host_name, token_path=None, token=None)This class can help you deal with the searching requirements of model.list_modelslist_models(model=None)List all model ifmodelis not specified.Ifmodelis specified, list all related models including extending and component.Parametersmodel:strModel ID.ReturnType:dictDictionary of each models.find_model_components_listfind_model_components_list(model)Get a list of the name of components ofmodel.This method will affect a private variable which has a getter methodget_component_dict().Parametersmodel:strModel ID.ReturnNoneget_component_dictget_component_dict()Get current found components of models.ReturnType:dictoflistofstrThe key is model, value is a list of component of this model.pickerpicker(model_folder, model_list, output_folder='picked')Instead of upload all models of a folder, you can use this method the pick the necessary models.This method will copy the models ofmodel_list, including the models which depend on it frommodel_folderto the folderoutput_folder.You can use Azure Digital Twins Explorer orAzure CLI commandto upload the folder of picked models.Parametersmodel_folder:strFolder path storing lots of models. This method will pick the models from here.model_list:listofstrList of model IDs.output_folder:strThe picked models will be copied to here.ReturnNoneadttools.helper.RelationshipHelperclass adttools.helper.RelationshipHelper(host_name, token_path=None, token=None)This class can help you deal with the CRUD requirements of relationships between digital twins.list_relationshipslist_relationships(source, rname=None)List all relationships which the source issource.Ifrnameis specified, the response will only contain the relationships with this name.Parameterssource:strDigital twin ID.rname:str(Default:None)Name of the relationship, if not specified, it will list all relationships.ReturnType:Response(from the libraryrequests)To get the content (JSON format string) of response, use.text.To get the status code of this HTTP request, use.status_code.add_relationshipadd_relationship(source, target, rname, init_property={})Add a relationship fromsourcetotargetwith namername. The properties of relationship can be add withinit_property.Parameterssource:strSource digital twin ID.target:strTarget digital twin ID.rname:strName of the relationship.init_property:dictInitial value given to the properties.should look like{"p_1": 123, "p_2":{"sub_p_1": "some value"}}ReturnType:Response(from the libraryrequests)To get the status code of this HTTP request, use.status_code.delete_relationshipdelete_relationship(source, rid)Delete a relationship with Idridfromsource.Parameterssource:strSource digital twin ID.rid:strID of the relationship.ReturnType:Response(from the libraryrequests)To get the status code of this HTTP request, use.status_code.find_relationships_with_targetfind_relationships_with_target(source, target, rname=None)List all relationships which the source issourceand the target istarget.Ifrnameis specified, the response will only contain the relationships with this name.Parameterssource:strSource digital twin ID.target:strTarget digital twin ID.rname:str(Default:None)Name of the relationship, if not specified, it will list all relationships.ReturnType:listofdictThedictinside contains 4 keys:relationshipId,relationshipName,sourceId,targetId.find_and_delete_relationshipsfind_and_delete_relationships(source, rname=None, target=None)Delete all relationships which the source issource.Ifrnameis specified, it will only delete the relationships with this name.Iftargetis specified, it will only delete the relationships which the target is this ID.Parameterssource:strSource digital twin ID.target:str(Default:None)Target digital twin ID.rname:str(Default:None)Name of the relationship, if not specified, it will delete all relationships matched.ReturnNoneadttools.helper.PropertyHelperclass adttools.helper.PropertyHelper(host_name, token_path=None, token=None)This class can help you deal with the CRUD requirements of properties of digital twins, including the properties of a component.Except for the methodget_twin_detail, the other methods are like a builder pattern in order to update multiple properties of a twin in one API calling.e.g.,from adttools.helper import PropertyHelper

ph = PropertyHelper(token_path="...", host_name="...")
ph.prepare_property(dtid="Room1")
  .update_property(key="temperature", value=60)
  .update_property(key="humidity", value=55)
  .add_property(key="name", value="sensor")
  .remove_property(key="remove")
  .submit()get_twin_detailget_twin_detail(dtid)Get the details of a digital twin (twin ID:dtid), including properties.Parametersdtid:strDigital twin ID.ReturnType:Response(from the libraryrequests)To get the content (JSON format string) of response, use.text.To get the status code of this HTTP request, use.status_code.prepare_propertyprepare(dtid)Start a process for updating property. You can use the methodsupdate_property,add_property,remove_propertyafter calling this method.Parametersdtid:strDigital twin ID.Returnselfprepare_componentprepare_component(dtid, component_path)Start a process for updating component. You can use the methodsupdate_property,add_property,remove_propertyafter calling this method.Parametersdtid:strDigital twin ID.Returnselfprepare_relationshipprepare_relationship(source, rid)Start a process for updating properties of a relationship. You can use the methodsupdate_property,add_property,remove_propertyafter calling this method.Parameterssource:strSource digital twin ID.rid:strID of the relationship.Returnselfsubmitsubmit()Submit the process.ReturnNoneupdate_propertyupdate_property(key, value)Add an "update" process to current updating process.Parameterskey:strKey of property.value:str,intorfloatValue of property.Returnselfadd_propertyadd_property(key, value)Add an "add" process to current updating process.Parameterskey:strKey of property.value:str,intorfloatValue of property.Returnselfremove_propertyremove_property(key)Add an "remove" process to current updating process.Parameterskey:strKey of property.Returnselfadttools.helper.TwinHelperclass adttools.helper.TwinHelper(host_name, token_path=None, token=None)This class can help you deal with the basic requirements of digital twins.add_twinadd_twin(dtid, model, init_property={}, init_component={})Add a digital twin with specified model ID, the initial value of properties and component can be set by using dictionary.Parametersdtid:strDigital twin IDmodel:strdtmi (digital twins model ID)init_property:dictInitial value given to the propertiesshould look like{"p_1": 123, "p_2":{"sub_p_1": "some value"}}init_component:dictInitial value given to the componentsshould look like{"c_1": {"c_1_property": "some value"}}ReturnType:Response(from the libraryrequests)To get the status code of this HTTP request, use.status_code.delete_twindelete_twin(dtid)Delete a digital twin with digital twin ID.Parametersdtid:strDigital twin IDReturnType:Response(from the libraryrequests)To get the status code of this HTTP request, use.status_code.adttools.helper.QueryHelperclass adttools.helper.QueryHelper(host_name, token_path=None, token=None)This class can help you deal with the requirements of querying digital twins and relationships.query_twinsquery_twins(dtid=None, condition=None)Query twins.Parametersdtid:str(Default:None)Source digital twin ID.condition:str(Default:None)Other condition can be placed here.ReturnType:listofdictThe matched twins.query_relationshipsquery_relationships(source=None, target=None, rname=None)Query relationships.Parameterssource:str(Default:None)Source digital twin ID.target:str(Default:None)Target digital twin ID.rname:str(Default:None)Relationship name.ReturnType:listofdictThe matched relationships.run_queryrun_query(self, query)Run a query string.Parametersquery:strQuery string.ReturnType:listofdictThe matched objects.adttools.helper.DeployHelperclass adttools.helper.DeployHelper(host_name, token_path=None, token=None)This class can help you deal with the requirements of batch deployment of digital twins.csv_deploycsv_deploy(path, atomic=True)Deploy digital twins with a csv file.Columns of this CSV file should bemodelid,dtid,init_property,init_component, ,rname,rtarget,init_rproperty.init_property,init_componentandinit_rpropertyare optional columns.modelid: model IDdtid: Twin IDinit_property: (JSON format) Can be empty, the initial value of properties.init_component: (JSON format) Can be empty, the initial value of components.rname: Relationship name, ifrnameis specified,rtargetis required. If multiple relationships are required, just add a new line withoutmodelidand using an existingdtid.rtarget: Target twin ID if a relationship (rname) is specified.init_rproperty: Initial value of properties of relationship if a relationship (rname) is specified.Parameterspath:strCSV file path.atomic:boolIf set asTrue, any step failed during this deployment will start a deletion process to delete the twins and relationships just created.If set asFalse, any step failed during this deployment will store to a CSV file (file name:<file name>_failed.csv) containing the failed twins and relationships. You can fix it and re-deploy it.ReturnNoneclearclear()Clean all twins and relationships.ReturnNone