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

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.

image

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.

  1. Wählen Sie Ihre CSV-Datei und das verwendete Trennzeichen.
  2. Im zweiten Schritt des Assistenten wählen Sie eine oder mehrere Gruppen aus, denen die importierten Benutzer als Mitglied hinzugefügt werden sollen.
  3. 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