REST API
Verwendung der Relution REST API (Application Programming Interface)
Die gesamte Funktionalität von Relution ist über eine umfangreiche REST API verfügbar. Sie können diese API nutzen, um Relution aus jeder anderen Anwendung oder per Skript zu Steuern.
API Access Tokens erzeugen
Sie benötigen ein API Access Token, um über Systeme oder Skripte von Drittanbietern auf Relution zuzugreifen. Sie können ein Access Token erstellen, indem Sie auf den
Benutzernamen in der oberen rechten Ecke des Relution Portals klicken. Klicken Sie dann auf
Profil > Access Token > Access Token hinzufügen
.
Benennen Sie das Token und kopieren Sie es.
Beispielscripte
Hier finden Sie einige Beispielskripte, die zeigen, wie die API verwendet werden kann:
Benutzer im CSV Dateiformat
Fügen Sie in die erste Zeile der .csv
-Datei eine Kopfzeile mit einer Liste
der gewünschten Eigenschaftsnamen ein. Die Reihenfolge der Spaltennamen ist nicht
relevant. Sie können auch Eigenschaften auslassen, die nicht benötigt
werden.
Pflichtfelder sind:
userid,email,first name,last name,password
Darüber hinaus können Sie bis zu 15 benutzerdefinierte Eigenschaften festlegen. Die
entsprechenden Kopfspalten sollten wie folgt benannt werden:
custom1-custom15
.
Sie können entweder das Beispiel verwenden oder eine Beispieldatei im Relution Portal herunter laden. Dazu klicken Sie auf Benutzer > Benutzer > Drei Punkte Menu > Benutzer per CSV importieren > Vorlage herunterladen
.
userid,email,first name,last name,password,phone number,position,country,managed apple id,custom1,custom2
user1,user1@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user1 position,user1 country,user1.id@company.com,43,Operations
user2,user2@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user2 position,user2 country,user2.id@company.com,24,Marketing
user3,user3@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user3 position,user3 country,user3.id@company.com,30,HR
user4,user4@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user4 position,user4 country,user4.id@company.com,32,Sales
user5,user5@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user5 position,user5 country,user5.id@company.com,45,Finance
user6,user6@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user6 position,user6 country,user6.id@company.com,30,Purchase
Hochladen von Benutzern über das Relution-Portal
Benutzer:innen können auf der Basis einer .csv
-Datei in der Relution UI importiert werden unter
Benutzer > Benutzer > Drei Punkte Menu > Benutzer per CSV importieren
.
- Wählen Sie Ihre CSV-Datei und das verwendete Trennzeichen.
- Im zweiten Schritt des Assistenten wählen Sie eine oder mehrere Gruppen aus, denen die importierten Benutzer als Mitglied hinzugefügt werden sollen.
- Die Benutzer:innen werden importiert und sind in der Übersicht sichtbar.
Benutzer über die Relution API anlegen
Um Benutzer:innen in Relution über die API auf der Grundlage einer .csv
-Datei zu erstellen, müssen Sie zwei
Dateien erstellen. Die erste ist die users.csv
Datei, die eine Zeile für jeden Benutzer:in in dem oben beschriebenen Format enthalten muss.
Die zweite Datei, die Sie benötigen, ist eine Bash-Skriptdatei (.sh). Kopieren Sie das folgende Beispiel und ersetzen Sie die folgenden Attribute durch Ihre Werte:
- <valid_Relution_API_Key>
- <relution_URL>
Speichern Sie beide Dateien.
Ergänzend muss das Script ausführbar gemacht werden:
chmod +x ./relutionCSVupload.sh
Führen Sie das Script im Terminal folgendermaßen aus:
./relutionCSVupload.sh -f users.csv
#!/bin/bash
#--------------------------------------------------------------------------------
# Headers
ACCESS_TOKEN="<valid_Relution_API_Key>"
while getopts "a:h:f:r:" opt; do
case $opt in
a) # apikey
APIKEY="$OPTARG"
;;
h) # host
HOST="$OPTARG"
;;
f) # File
FILE="$OPTARG"
;;
r) # Role
ROLE="$OPTARG"
;;
\?)
echo "Unknown option -$OPTARG" >&2
;;
esac
done
APIKEY=$ACCESS_TOKEN
HOST='https://<relution_URL>'
# Remember to avoid the last backslash
echo $HOST
if [[ -z $APIKEY ]]; then
echo "Please specify an API Key (-a)"
exit 1
fi
if [[ -z $HOST ]]; then
echo "Please specify a Host URL (-h)"
exit 1
fi
if [[ ! -f $FILE ]]; then
echo "Please specify an existing csv file (-f)"
exit 1
fi
if [[ -z $ROLE ]]; then
ROLE=Organame%20Device%20User
fi
ERRORS=0
echo -n "Importing users from $FILE to Relution server ${HOST} as '${ROLE//%20/ }'... "
echo
echo
# On missing errors information, you can try to run the following curl expression directly to see the full output
# curl -X POST -H "Accept: application/json" -H "X-User-Access-Token: $APIKEY" -F "file=@$FILE" "$HOST/gofer/security/user/import?overwrite&role=$ROLE"
HTTP_ERROR=$(curl -X POST -H "Accept: application/json" -H "X-User-Access-Token: $APIKEY" -F "file=@$FILE" -sw "%{http_code}" "$HOST/gofer/security/user/import?overwrite&role=$ROLE")
echo $HTTP_ERROR
HTTP_ERROR=${HTTP_ERROR: -6}
HTTP_ERROR=${HTTP_ERROR: 3}
if [[ $HTTP_ERROR -ne 200 ]]; then
ERRORS=$((ERRORS + 1))
echo "$HTTP_ERROR"
else
echo "Done. No Errors."
fi
if [[ $ERRORS -gt 0 ]]; then
echo "Error(s) during upload: ($ERRORS)"
exit $ERRORS
fi
echo "All done."
echo
Eine neue Organisation anlegen
#!/bin/bash
#--------------------------------------------------------------------------------
# Web service URL, change the server name as needed
SVR_URL="https://<myserver>/api/v1/security/organizations/creationWizardRequests"
# Access token of System Admin, create it by opening https://<server>/#/profile
# Open this URL in your browser while logged in as System Administrator.
# NOTE: This is not an URL you can reach through clicking through the portal!
ACCESS_TOKEN="<sysadmin_api_token>"
# HTTP Headers
ACCEPT="application/json"
ACCEPT_CHARSET="UTF-8"
# Input JSON, change values as needed
read -r -d '' JSON_BODY << 'EOF'
{
"name": "My Orga",
"uniqueName": "myorga",
"orgaMailReplyTo": [],
"passwordPolicy": {
"allowSimplePassword": false,
"maximumPasswordAge": 0,
"minimumNumbersOfDigits": 0,
"minimumNumbersOfLowerCaseLetters": 0,
"minimumNumbersOfUpperCaseLetters": 0,
"minimumPasswordLength": 8,
"requiredNumbersOfSymbols": 0
},
"orgaName": "myorga",
"orgaFullName": "My Orga",
"orgaContactName": "MyOrga Admin",
"orgaContactEMail": "myorgaadmin@mail.de",
"orgaAdminUser": "myorgaadmin",
"orgaAdminGivenName": "MyOrga",
"orgaAdminSurName": "Admin",
"orgaAdminPwd": "myorgaadminpw",
"orgaAdminEmail": "myorgaadmin@mail.de"
}
EOF
echo "Creating new Relution Organization at $SVR_URL..."
echo
# No changes should be required beyond this line...
RESPONSE=$(curl -X POST \
${SVR_URL} \
-H "X-User-Access-Token: $ACCESS_TOKEN" \
-H "Accept: $ACCEPT" \
-H "Accept-Charset: $ACCEPT_CHARSET" \
-H "Content-Type: $ACCEPT" \
--write-out " HTTP_STATUS=%{http_code}" \
--silent \
-d "$JSON_BODY")
if [[ $RESPONSE =~ HTTP_STATUS=([0-9]+) ]]; then
HTTP_STATUS=${BASH_REMATCH[1]}
fi
if [[ $HTTP_STATUS -lt 200 || $HTTP_STATUS -gt 299 ]]; then
echo " HTTP status: $HTTP_STATUS"
else
echo "Done. No Errors."
fi
echo
Abfrage der in einer bestimmten Organisation registrierten Geräte
#!/bin/bash
#--------------------------------------------------------------------------------
# Web service URL, change the server name as needed
SVR_URL="https://<myserver>/api/v2/devices/baseInfo/query"
# Access token of an Orga Admin, create it by clicking on the user name in the top right corner of the portal.
# Then click "Profile", "Access tokens", "Add".
ACCESS_TOKEN="<orga_admin_access_token>"
# HTTP Headers
ACCEPT="application/json"
ACCEPT_CHARSET="UTF-8"
# Query example
read -r -d '' JSON_BODY << 'EOF'
{
"limit": 10,
"offset": 0,
"getNonpagedCount": true,
"sortOrder": {
"sortFields": [
{
"name": "lastConnectionDate",
"ascending": false
}
]
},
"filter": {
"type": "logOp",
"operation": "AND",
"filters": [
{
"type": "stringEnum",
"fieldName": "platform",
"values": [
"ANDROID",
"ANDROID_ENTERPRISE",
"IOS"
]
},
{
"type": "stringEnum",
"fieldName": "status",
"values": [
"COMPLIANT",
"INACTIVE"
]
}
]
}
}
EOF
echo "Querying devices at $SVR_URL..."
echo
# No changes should be required beyond this line...
RESPONSE=$(curl -X POST \
${SVR_URL}${FILTER} \
-H "X-User-Access-Token: $ACCESS_TOKEN" \
-H "Accept: $ACCEPT" \
-H "Accept-Charset: $ACCEPT_CHARSET" \
-H "Content-Type: $ACCEPT" \
--write-out " HTTP_STATUS=%{http_code}" \
--silent \
-d "$JSON_BODY")
if [[ $RESPONSE =~ HTTP_STATUS=([0-9]+) ]]; then
HTTP_STATUS=${BASH_REMATCH[1]}
fi
if [[ $HTTP_STATUS -lt 200 || $HTTP_STATUS -gt 299 ]]; then
echo "HTTP status: $HTTP_STATUS"
else
echo "Done. Parsing ouput..."
echo
echo "${RESPONSE%HTTP_STATUS*}" | jq '.results[].name'
fi