CloudCenter-API

cloud center API

 Einleitung

In diesem Thema findest du allgemeine Informationen zur cloud center-API, dem Funktionsumfang sowie zu den Kenntnissen, die hilfreich beim Verwenden der API-Funktionen sind.

 Funktionsumfang von d.velop cloud center

Das d.velop cloud center ist die Self-Service-Oberfläche für die d.velop cloud. App Builder können hier ihre Apps registrieren und verwalten, sodass Endkunden diese für ihre d.velop cloud buchen können.

 Technische Hintergrundinformationen

Das cloud center ist ein Tool, welches über das Internet mit deiner App kommuniziert. Daher solltet du dich als App Builder mit folgenden Webtechnologien auskennen: - HTTPS - RESTful - JSON

Damit die Kommunikation zwischen dem cloud center und deiner App abgesichert ist, sollten dir die Hash-Funktion SHA256 und der Authentifizierungscode HMAC bekannt sein.

In den nachfolgenden Kapiteln erfährst du mehr über das App Secret sowie den Signaturprozess. Das App Secret und der Signaturprozess stellen sicher, dass die Kommunikation zwischen deiner App und dem cloud center abgesichert ist.

 Grundlegendes zum App Secret

Das App Secret besteht aus zufällig zusammengestellten Bytes, welche in einen Base64-String umgewandelt wurden. Bevor du das App Secret verwenden kannst, musst du den Base64-String in Bytes umwandeln (decodieren). Viele Programmiersprachen besitzen Bibliotheken, die das Umwandeln für dich übernehmen.

Das App Secret wird zur Absicherung der Kommunikation des Mandanten mit deiner App verwendet (siehe Mandanten Header). Zudem wird es auch zur Absicherung der Events verwendet, die vom cloud center gesendeten wurden.

Nach der Erstellung der App im cloud center siehst du das App Secret als Base64-String im Klartext auf der Bearbeitungsseite deiner App im Bereich technische Details. Du solltest als erstes das App Secret kopieren und in deiner App hinterlegen. Nach der ersten Änderung wird dein App Secret nurnoch verschlüsselt dargestellt. Solltest du vergessen haben, das App Secret zu kopieren, kannst du dir jederzeit im Bereich technische Details ein neues App Secret erstellen lassen. Wechsle dazu in den Bearbeitungsmodus und wähle die Schaltfläche Neues Secret generieren aus. Im folgenden Dialog kannst du dir ein neues App Secret erzeugen lassen. Kopiere das App Secret und hinterlege es in deiner App, da deine App sonst nicht mehr erreichbar ist.

 Grundlegendes zum Signaturprozess

Um sicherzustellen, dass eine eintreffende Anfrage vom d.velop cloud center stammt, musst du in deiner App die Signatur auf Gültigkeit prüfen. Dazu erstellst du nach dem gleichen Prozess die Signatur basierend auf dem App Secret, welches nur dir und dem d.velop cloud center bekannt ist. Stimmt deine berechnete Signatur mit der aus der Anfrage überein, kannst du dir sicher sein, dass die Anfrage vom d.velop cloud center gesendet wurde.

Anfrage Header

Folgende Header müssen bei der Anfrage des cloud centers an deine App angeliefert werden:

  • Authorization: Bearer Token mit der berechneten Signatur in hexadezimaler Schreibweise.
  • x-dv-signature-headers: Kommaseparierte Liste (ohne Leerzeichen) aller für die Signatur genutzten Header-Namen in Kleinbuchstaben. Die Auflistung enthält auch den eigenen Header-Namen.
  • x-dv-signature-algorithm: Für die Signatur verwendeter Algorithmus. Zur Zeit steht dort DV1-HMAC-SHA256.
  • x-dv-signature-timestamp: Zeitstempel in UTC-Zeit nach ISO 8601 (Format: "yyyy-MM-ddTHH:mm:ssZ", z.B.: 2019-08-23T08:49:42Z).

 Implementation des Signaturprozesses

Im folgenden erfährst du anhand eines Beispiels mehr über die notwendigen Schritte im Signaturprozess.

Verwendetes App Secret:

   
    Rg9iJXX0Jkun9u4Rp6no8HTNEdHlfX9aZYbFJ9b6YdQ=

Beispielname deiner App:

   
    myApp

Verwendeter Payload/Anfrage Body:

   
    {"type":"subscribe","tenantId":"id","baseUri":"https://someone.d-velop.cloud"}\n

 Sortieren und Normalisieren der Header

Es werden alle unter x-dv-signature-headers angegebenen Header alphabetisch sortiert. Zur weiteren Verarbeitung werden die Header nach folgemdem Muster aneinandergereiht:

Schema:

   
    Lowercase(header1) + ":" + Trim(value1) + "\n" +
    Lowercase(header2) + ":" + Trim(value2) + "\n" +
    ...
    Lowercase(headerN) + ":" + Trim(valueN) + "\n"

Beispiel

   
    "x-dv-signature-algorithm:DV1-HMAC-SHA256\nx-dv-signature-headers:x-dv-signature-algorithm,x-dv-signature-headers,x-dv-signature-timestamp\nx-dv-signature-timestamp:2019-08-09T08:49:42Z\n"

 Normalisierung der Anfrage

In diesem Schritt werden die Bestandteile der Anfrage in normalisierter Form mit einem Zeilenumbruch als Trennzeichen aufgelistet.

Schema:

   
    HTTP-Verb            + "\n" +   // GET, PUT, POST...
    Pfad der Resource    + "\n" +   // With leading slash
    Querystring          + "\n" +   // Without ?, urlencoded
    Headers              + "\n" +   // Normalized header string
    SHA256(Payload)                 // SHA256-Hash of request body as hex value

Beispiel

   
   "POST\n/myapp/dvelop-cloud-lifecycle-event\n\nx-dv-signature-algorithm:DV1-HMAC-SHA256\nx-dv-signature-headers:x-dv-signature-algorithm,x-dv-signature-headers,x-dv-signature-timestamp\nx-dv-signature-timestamp:2019-08-09T08:49:42Z\n\nc2a6fefc93b809eeaf2f069504fe8e02b0f3341b3c5e488e6a402ca45301415c"

 Bilden eines Hashwerts in Hexadezimal

Verwende zum Erstellen der Hash-Werte den Hash-Algorithmus HMAC SHA256 und die Bibliothek der jeweiligen Programmiersprache. Zum Bilden des Hashwertes wird zuerst ein SHA-256-Hash aus dem normalisierten Anfrage-String berechnet. Der Hash wird anschließend in einen Hexadezimalwert mit Kleinbuchstaben umgewandelt.

Beispiel

   
    cc514231eb4ebab401cc8a117d16fe1cfb9fff13e0ebaf110b14c59d4e735fd1

 Berechnen der Signatur

Aus dem berechneten hexadezimalen Anfrage-String und dem App Secret wird nun mittels HMAC-SHA-256-Verfahren eine Prüfsumme berechnet. Das Ergebnis wird wiederum in einen Hexadezimalwert mit Kleinbuchstaben umgewandelt.

Beispiel

   
    f6c0a9b19244e4925ad890dea7c0a102ab1ce1008f8390e2888307190a291074

 Prüfen der Signatur

Die Prüfung der Signatur besteht aus zwei Teilen. Mithilfe des Zeitstempels im Header x-dv-signature-timestamp siehst du, ob die Anfrage aktuell ist. Der Zeitstempel bezieht sich auf die UTC-Zeit beim Absenden der Anfrage an deine App. Um Zeitdifferenzen zwischen Servern auszugleichen, sind Anfragen für den Zeitraum von 5 Minuten vor bzw. 5 Minuten nach dem angegebenen Zeitstempel gültig. Wenn die angegebene Zeit außerhalb des Zeitfensters ist, muss die Signatur als ungültig betrachtet und die Anfrage mit dem HTTP-Status "403 Forbidden" abgelehnt werden. Durch anwenden des beschriebenen Signaturprozesses berechnet die App nun eine Vergleichssignatur. Stimmt die berechnete Signatur nicht mit dem hexadezimalen Wert aus dem Authorization-Header überein, so ist die Anfrage ebenfalls mit dem HTTP-Status "403 Forbidden" abzulehnen.

Hinweis

Hinweis Entferne vor dem Vergleich das Wort "Bearer", um den reinen hexadezimalen Wert zu erhalten.

 Verwenden der API-Funktionen

Das cloud center stellt eine API-Schnittstelle zur Verfügung, mit der du beispielsweise sehen kannst, wann deine App gebucht wurde.

 Grundlegendes zu den Ereignissen des App-Lebenszyklus

Damit du weißt, wann deine App beispielsweise von einem Kunden gebucht wurde, veröffentlicht das cloud center vier Ereignistypen (subscribe, unsubscribe, resubscribe und purge), die nachfolgend beschrieben werden. Was du tun musst, um diese Ereignisse zu Empfangen und zu verarbeiten, erfährst du im Kapitel "Empfangen von Ereignissen".

Image of lifecycle-events

In manchen Fällen wird ein Ereignis mehrfach an deine App gesendet, z.B. wenn ein Kunde eine App bucht, die abhängig von deiner App ist. Daher musst du immer vorher prüfen, ob du das Ereignis bereits erhalten hast. Wenn du das Ereignis noch nicht erhalten hast, musst du es dem Ereignistypen entsprechend behandeln.

 Ereignistyp "subscribe"

Du empfängst dieses Ereignis sobald ein Kunde deine App bucht. Je nach Funktion deiner App ist eine Initialisierung deiner App notwendig. Beispielsweise, wenn du kundenspezifische Informationen in deiner Datenbank speichern musst.

 Ereignistyp "unsubscribe"

Das unsubscribe-Ereignis erhältst du, wenn der Kunde deine App nicht mehr verwenden möchte und kündigt. Dies ist für dich erstmal nur ein Hinweis darauf, dass deine App vom Kunden nicht mehr genutzt wird. Sobald das unsubscribe-Ereignis gesendet wurde, ist deine App nicht mehr in der d.velop cloud des Kunden verfügbar. Der Kunde kann daher nicht mehr mit deiner App interagieren. Auf keinen Fall darfst du die Daten des Kunden löschen (siehe: Eventtyp purge).

 Ereignistyp "resubscribe"

Das resubscribe-Ereignis empfängst du, falls ein Kunde sich nach dem Kündigen umentscheidet und deine App doch weiter verwenden möchte.

 Ereignistyp "purge"

Nachdem ein Kunde die App gekündigt hat und die Karrenzzeit abgelaufen ist, empfängt deine App das purge-Ereignis. Dieses Vorgehen schützt den Kunden vor einer vorzeitigen Löschung seiner Daten, nachdem er gekündigt hat. Sobald du dieses Ereignis empfängst musst du alle Daten des Kunden löschen. Welche Daten du löschen musst, kannst du dem Ereignis entnehmen.

 Empfangen von Ereignissen

In diesem Abschnitt erhältst du Informationen zu den Voraussetzungen für den Empfang von Ereignissen.

HTTP-Anfrage

Deine App muss eine Ressource namens "dvelop-cloud-lifecycle-event" zur Verfügung stellen.

Die Anfrage vom cloud center sieht wie folgt aus:

   
   POST  https://myapp1.example.com/myapp1/dvelop-cloud-lifecycle-event
   Content-Type: application/json

Event Body

Die Anfrage des cloud centers enthält nachfolgenden Body in Form eines JSON-Dokuments.

  • "type": Enthält den jeweiligen Eventtypen. Je nachdem welcher Type gesendet wurde, muss deine App entsprechende Aktionen ausführen.
  • "tenantId": Dies ist die eindeutige Identifikationsnummer der d.velop cloud des Kunden.
  • "baseUri": Unter dieser Adresse ist die d.velop cloud des Kunden erreichbar. Die BaseUri wird immer absolut und ohne Slash am Ende mitgeliefert.

Beispiel

   
{
    "type": "subscribe",
    "tenantId": "xyz",
    "baseUri": "https://mandant.d-velop.cloud"
}

 Überprüfen der Ereignisse

Damit du sicherstellen kannst, dass die Anfrage wirklich vom cloud center kommt, ist die Anfrage mit dem beschriebenen Signatur-Mechanismuses abgesichert. Sobald du ein Ereignis empfängst, musst du prüfen, ob die Anfrage richtig signiert ist (siehe Grundlegendes zum Signaturprozess.

d.velop store markup

 Übersicht aller Elemente

Nachfolgend erfährst du, welche Elemente dir in der App Beschreibung deines Produkts im cloud center zur Verfügung stehen.

 Überschrift-Element

Überschrift Element

Mit dem Überschriften-Element struktuierst du deine Seite, indem du deine Inhalte inhaltlich gruppierst.

   
    <h2>Unterschreiben Sie Dokumente digital in 30 Sekunden</h2>

Befindet sich die Überschrift innerhalb eines anderen Elements, wird ihre Darstellung an das Element angepasst. Siehe z.B. Medien und Text-Element.

 Einstellungen

Das Überschrift-Element bietet die Optionen "h2" und "h3". Die Gliederung hat der im Web üblichen Hierarchie zu entsprechen.

  • Abschnitt 1: h2
    • Abschnitt 1.1: h3
    • Abschnitt 1.2: h3
  • Abschnitt 2: h2
  • Abschnitt 3: h2
    • Abschnitt 3.1: h3

In Html:

   
<h2>Abschnitt 1</h2>
<h3>Abschnitt 1.1</h3>
<h3>Abschnitt 1.2</h3>
<h2>Abschnitt 2</h2>
<h2>Abschnitt 3</h2>
<h3>Abschnitt 3.1</h3>

 Listen-Element

Listen Element

Mit dem Listen-Element organisierst du Inhalte übersichtlich auf kleinem Raum. Eine Liste ist einer Tabelle im Zweifel immer vorzuziehen.

   
<ul>
    <li>Listenpunkt 1</li>
    <li>Listenpunkt 2</li>
    <li>Listenpunkt 3</li>
</ul>

 Einstellungen

Das Listen-Element bietet die Optionen "strong" und "em", um Wörter hervorzuheben.

   
<ul>
    <li>
    <strong>Authentifizierung</strong> über Personalausweis
    </li>
    <li>Konkrete Anforderung an die Identifizierung</li>
    <li>
    <em>Unter Berücksichtigung der gesetzlich vorgeschriebenen Aushänge für Verwaltungen</em>
    </li>
</ul>

 Banner-Element

Banner Element

Mit dem Banner-Element legst du ein Bild und Text auf einen Farbverlauf. Dieses Element stellt die maximale Aufmerksamkeit der Besucher sicher.

   
<div class="dv-banner">
    <img
        src="https://..."
        alt="Produktname - Startseite der App"
    />
    <p>
        Auf Mausklick verfügbar. Flexibel erweiterbar. Monatlich nach Ihrem Nutzen abgerechnet.
    </p>
</div>

 Einstellungen

Das Banner-Element bietet die Option, den Ververlauf über die Modifier-Klasse "dv-banner--transparent" auszublenden.

Transparentes Banner Element

   
<div class="dv-banner dv-banner--transparent">
    ...
</div>

 Medien und Text-Element

Media-Text Element

Mit dem Medien und Text-Element setzt du ein Bild neben einen Text. Der Text wird am unteren Bildrand ausgerichtet.

   
<div class="dv-media-text">
    <img
        src="https://..."
        alt="Produktname - Verwaltung im Dashboard"
    />
    <div>
        <h3>Zentraler Zugriff auf alle Informationen</h3>
        <p>Als Dokumentenmanagementsystem wird d.velop documents zur zentralen Drehscheibe für Dokumente in Ihrem Unternehmen. Lösen Sie Datensilos auf und arbeiten Sie von einem zentralen Punkt mit Lieferscheinen, Rechnungen, E-Mails und Verträgen.</p>
    </div>
</div>

 Einstellungen

Das Medien und Text-Element bietet die Option, die Reihenfolge des Medien- und Text-Containers zu tauschen.

   
<div class="dv-media-text">
    <img
        src="https://..."
        alt="Produktname - Desktop-Ansicht"
    />
    <div>
        <p>Erst Bild, dann Text</p>
    </div>
</div>

<div class="dv-media-text">
    <div>
        <p>Erst Text, dann Bild</p>
    </div>
    <img
        src="https://..."
        alt="Produktname - Mobil-Ansicht"
    />
</div>

 Feature-Element

Feature Element

Mit dem Feature-Element hebst du die Vorteile deines Produktes hervor und beschreibst sie in knappen Sätzen.

   
<div class="dv-feature">
    <img
        src="https://..."
        alt="Produktname - Desktop-Ansicht"
    />
    <h3>Einfache Signatur</h3>
    <ul>
        <li>Urheber kann identifiziert werden</li>
        <li>Keinerlei Anforderungen an die Identifizierung (z.B. E-Mail)</li>
    </ul>
</div>

 Einstellungen

Die im Beispiel aufgeführten Elemente können beliebig ausgetauscht, erweitert oder entfernt werden.

Modified Feature Element

   
<div class="dv-feature">
    <img
        src="https://..."
        alt="Produktname - Desktop-Ansicht"
    />
    <p>Schaffen Sie die Basis für eine revisionssichere Archivierung.</p>
</div>

 Spalten-Element

Spalten Element

Mit dem Spalten-Element kannst du beliebige Inhalte in bis zu vier Spalten einfügen.

   
<div class="dv-columns">
    <div class="dv-feature">...</div>
    <div class="dv-feature">...</div>
    <div class="dv-feature">...</div>
    <div class="dv-feature">...</div>
</div>

 Einstellungen

Das Spalten-Element bietet die Optionen ".dv-columns--2", ".dv-columns--3" und ".dv-columns--4". Diese sogenannten Modifier-Klassen erzwingen einen Zeilenumbruch nach dem 2. (bzw. 3. oder 4.) Kind-Element. Außerdem sorgen sie dafür, dass Kind-Elementen eine maximale Breite von 1/n einhalten.

   
<div class="dv-columns dv-columns--2">
    <!-- Element 1/2 breit -->
    <div class="dv-feature">...</div>
    <div class="dv-feature">...</div>

    <!-- Erzwungener Zeilenumbruch, Element 1/2 breit -->
    <div class="dv-feature">...</div>
    <div class="dv-feature">...</div>

    <!-- Erzwungener Zeilenumbruch, Element 1/2 breit, mittig -->
    <div class="dv-feature">...</div>
</div>

 Tabellen-Element

Der Einsatz dieses Elements setzt gute HTML-Kenntnisse voraus.

Desktop:

Table Element

Mobil:

Mobile Table Element

Mit dem Tabellen-Element stellst du Features von App-Varianten vergleichbar dar. Die Akzentfarbe der Tabelle hängt vom gewählten Theme der App ab (hier "Frosty Nova").

Damit in der Mobilansicht der Name der jeweiligen Variante angezeigt wird, muss dieser in jeder Zelle eingefügt werden. Siehe beliebiges "td span" Element im "body" Bereich.

   
<table>
    <thead>
        <tr>
            <th>&nbsp;</th>
            <th>Starter Version</th>
            <th>Premium Version</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <th>Vorhersagezeitraum:</th>
            <td>
                <span>Starter Version</span>
                <ul>
                    <li>7 Tage</li>
                </ul>
            </td>
            <td>
                <span>Premium Version</span>
                <ul>
                    <li>7 / 14 / 30 Tage</li>
                    <li>2 / 4 / 8 Wochen</li>
                    <li>1 / 2 / 3 Monate</li>
                </ul>
            </td>
        </tr>
        <tr>
            <th>Gruppierungsmöglichkeiten:</th>
            <td>
                <span>Starter Version</span>
                <ul>
                    <li>Keine</li>
                </ul>
            </td>
            <td>
                <span>Premium Version</span>
                <ul>
                    <li>Gruppierung (Splits) nach einer Hauptvariable</li>
                    <li>Gruppierung (Splits) nach einer sekundären Variablen</li>
                </ul>
            </td>
        </tr>
        <tr>
            <th>Weitere Daten zur Verbesserung der Prognose:</th>
            <td>
                <span>Starter Version</span>
                <ul>
                    <li>Kalendarische Informationen</li>
                </ul>
            </td>
            <td>
                <span>Premium Version</span>
                <ul>
                    <li>Interne Daten (z.B. Sales-Aktionen)</li>
                    <li>Kalendarische Informationen</li>
                    <li>Feiertage (national und international)</li>
                </ul>
            </td>
        </tr>
    </tbody>
</table>

 Hilfsklassen

Hilfsklassen dienen der Feinjustierung der bislang aufgeführten Elemente. Sie sind so erstellt worden, dass sie die Einstellungen eines Elements ohne Rücksicht auf dessen ursprüngliche Gestaltung überschreiben.

 Textausrichtung erzwingen

Mit diesen Klassen passt du die Ausrichtung deiner Texte an.

   
<p class="dv-text-left">Linksbündig</p>
<p class="dv-text-center">Mittelsatz / Zentriert</p>
<p class="dv-text-right">Rechtsbündig</p>

Du könntest z.B. den Beschreibungstext eines Features linksbündig, anstatt mittig anordnen.

   
<div class="dv-feature">
    <img
        alt="..."
        src="https://..."
    >
    <h3>Normale Überschrift</h3>
    <p class="dv-text-left>Linksbündiger Text</p>
</div>