Beiträge in diesem Abschnitt

Nutzung der API Anbindung

Jörn Rettweiler
  • Erstellt
  • Aktualisiert
Folgen

Themen in Übersicht:

  1. API Key Erstellen
  2. Abfragemöglichkeiten
  3. Code Beispiele
  4. Oft gestellte Fragen

API Key Erstellen

  • Hierzu unter dem Benutzericon (1) > Mein Account (2) > Reiter "API-Zugang" (3) auswählen.

 

Zum Anlegen eines neuen API-Keys auf das "Plus" (1) klicken.

 

  • Es wird direkt ein API-Key und API-Secret generiert
    • der API Key ist immer sichtbar.
    • das API Secret ist nur in dieser Ansicht einmalig sichtbar, nach schließen des Menüs ist dieser nie wieder abrufbar. Ein neuer kann jedoch immer wieder erstellt werden. 

    • Die Client ID ist unter der Spalte API Key gelistet (wird künftig in Client ID umbenannt)

 

  • Zum Löschen des API Keys auf die Mülltonne (1) klicken.

 

Abfragemöglichkeiten

Folgende Sachen können von der API abgefragt / modifiziert werden

  • Abruf der hinterlegten Namen und Eigenschaften (nicht die Werte) von Elementen und Attributen (siehe Beispiel unten)
  • Abruf von Attributwerten
  • Modifikation von Attributwerten
  • ...

Achtung: Die Funktionen der API sind je nach Rollenrecht eingeschränkt, prinzipiell kann jeder Benutzer eine API Schnittstelle einrichten. Sollten gewissen Abrufe oder Modifikationen nicht möglich sein, kann Ihr Rollenrecht eingeschränkt sein, ein höheres / anderes Rollenrecht kann - je nach Hintergrund - durch den Ansprechpartner seitens der Kaulquappe generiert werden.

 

Code Beispiele

Das unten gezeigte Beispiel ermöglicht unter der Verwendung von Visual Studio Code und der REST Client Extension, die folgenden Funktionen auszuüben:

  • 1. Login auf big
  • 2. Token in Variable speichern
  • 3 Elementdefinitionen anfordern (inkl. der Attribute)
  • 4. Elemente eines bestimmten Typen anfordern
  • 5 Elemente eines bestimmten Geschosses anfordern
  • 6. Attributwerte überschreiben

Beispiel 1

@host=https://zendesk-ch.build-big.ch #Domainname
@client id=[big Domain name] api
@client secret-[Client Secret aus from big API] 
@grant type client credentials
@instance=[big Domain name]@projectId=[big Project ID]


###
###1. Login:
# @name login

POST https://(linstance)j_build-big.ch/auth/login/token
Content-Type: application/x-www-form-urlencoded

client id-{{client id}}&client secret={{client_secret}}&grant_type-{{grant type}}

### 2 Store access token in var
@accessToken-{{login.response.body. $.access_token}}
#@accessToken-{{login.response.body. $.access_token}}

### 3. Get all element definitions
# @name elements
GET https://{{linstance}}.build-big.ch/api/entity/elements
Authorization: Bearer {{accessToken}}
Content-Type: application/json
X-PROJECT-ID: {{projectid}}

### 4 Get element entities
# @name entities
###

@element_id = {{elements.response. body. $.elements[0].id}}
GET https://{{instance}}.build-big.ch/apt/entity/{{element_id}}
Authorization: Bearer {{accessToken}}
Content-Type: application/son
X-PROJECT-ID: {{projectid}}

###
# 5 Get specific entities
###

@key=Geschoss
@system_id=1. Obergeschoss
GET https://{{lnstance}}.build-big.ch/api/entity/{{element_id}}?key={{key}}&value={{System_id}}
Authorization: Bearer {{accessIoken}}
Content-Type: application/json
X-PROJECT-ID: {{projectid}}

###
# 6 Attribute update
###

@entities_id={{entities.response.body.$.entities[0].id}}
PUT https://[[instance]].build-big.ch/api/entity/{{element_id}}/{{entity_id}}
Authorization: Bearer {{accessToken}}
Content-Type: application/json
X-PROJECT-ID: {{projectId}}


Beispiel 2

 

@host=https://hal3000.build-big.ch
@client_id=
@client_secret=
@grant_type=client_credentials
#@project_id=


### 1 Login:
# @name login
POST {{host}}/auth/login/token
Content-Type: application/x-www-form-urlencoded

client_id={{client_id}}&client_secret={{client_secret}}&grant_type={{grant_type}}

### 1.1 Store access token in var
@access_token={{login.response.body.$.access_token}}
#@refresh_token={{login.response.body.$.refresh_token}}

###
# 2 Get versions
# @name verions
GET {{host}}/api/entity/versions
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

### 3 Get element definitions
# @name elements
GET {{host}}/api/entity/elements
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

### 3.1 Get type definitions
# @name types
@element_id={{elements.response.body.$.elements[0].id}}
GET {{host}}/api/entity/{{element_id}}/types
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

### 3.2 Get entities (instances)
# @name entities
@element_id={{elements.response.body.$.elements[0].id}}
GET {{host}}/api/entity/{{element_id}}
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

###
# 3.3 Get specfic entities (attribute filter)
@key=Objectnumber
@value={{entities.response.body.$.entities[0].attributes.Objectnumber}}
GET {{host}}/api/entity/{{element_id}}?key={{key}}&value={{value}}
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

###
# 3.4 Get specfic entities (id)
# @name entity
# instance id: id of the requested instance
# version id: id of the requested version (optional)
#@instance_id = {{entities.response.body.$.entities[0].id}}
@instance_id={{entities.response.body.$.[0].id}}
#@version_id={{entities.response.body.$.[0].id}}
GET {{host}}/api/entity/instance/{{instance_id}}
#?version_id={{version_id}}
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

###
# 3.5 Get specfic entities (delta to current)
# @name delta_current
# Status: INSERTED, DELETED, UPDATED, UNMODIFIED (defaults to INSERTED, DELETED, UPDATED)
# version id: former version to compare
# full: flag for requesting only changes or full entity/instance data (optional)
@status=
@version_id={{verions.response.body.$.[0].id}}
@full=false
GET {{host}}/api/entity/{{element_id}}/delta/{{version_id}}?status={{status}}&full={{full}}
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

###
# 3.6 Get specfic entities (delta between versions)
# @name delta_versions
# current version id: later version (optional)
@current_version_id={{verions.response.body.$.[1].id}}
GET {{host}}/api/entity/{{element_id}}/delta/{{version_id}}/{{current_version_id}}?status={{status}}&full={{full}}
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

###
# 4.1 Create type
# @name new_type
@type_name=<<new type>>
POST {{host}}/api/entity/{{element_id}}/type
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

{
"name": "{{type_name}}",
"attributes": {
"Wert": "",
"Ganzzahl": 3,
"Double": 0.33
}
}

###
# 4.2 Create entity (instance)
# @name new_instance
@instance_name=<<new instance>>
POST {{host}}/api/entity/{{element_id}}
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

{
"entity_type_name": "{{type_name}}",
"attributes": {
"Name": "{{instance_name}}",
"Schwelle": 30
}
}

###
# 4.3 Create version
# @name new_version
@version_name=<<new version>>
@version_description=<<new version>>
POST {{host}}/api/entity/{{element_id}}
Authorization: Bearer {{access_token}}
Content-Type: application/json
#X-PROJECT-ID: {{project_id}}

{
"name": "{{version_name}}",
"description": "{{version_description}}"
}

 

 

 

Anmerkungen zum Beispiel

Die Instance bzw. die big Domain name kann aus dem Beispiel https://(linstance)j_build-big.ch/auth/login/token kann wie nachfolgend aus dem Domainnamen   ① bezogen werden im folgenden ist dies demo-de.

 

Die Variable projectId bzw. big Project ID kann aus der Projektübersicht und dort aus der Projektkachel nebenstehend zum # ① entnommen werden, im Beispiel ist dies 51 .

 

Die Variable element_id kann unter dem Elementen und Attributen, nebenstehend zu den Elementnamen nach der Raute # ① bezogen werden für die ARC_Bodenaufbauten ist dies beispielsweise 25.

 

Für eine Abfrage einer spezifischen (Attributs-)Spalte wird im nachfolgenden Beispiel das Attribut System_id abgefragt. GET https://{51}.build-big.ch/api/entity/{25}?key={{key}}&value={{System_id}}

 

Für den schreibenden Zugriff braucht es das entsprechende Rollenrecht und die korrekte Zuweisung der Disziplin auf die das Attribut zugewiesen werden soll.

Prinzipiell sind die API Abfragen aus der REST-API auch mittels andere Programmiersprachen möglich.

 

Oft gestellte Fragen

  • Bei weiteren Fragen, gerne eine Email an: info@kaulquappe.com

Verwandte Beiträge

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.