Nachrichtenformate für Anforderung und Antwort

Die Anforderung

Jede API-Methode in

Adaptive Planning

Die API erwartet, dass das XML-Dokument in seinem Text eine Struktur hat, die wie folgt aussieht:


    <?xml version='1.0' encoding='UTF-8'?>
    <call method="exportData" callerName="a string that identifies your client application">
       <credentials login="sample@company.com" password="my_pwd"/>              
       method specific data goes here
    </call>

Hier ist eine Beschreibung der einzelnen relevanten Positionen:

Diese Zeile gibt an, dass die nachfolgenden Daten in UTF-8 XML-codiert sind.

Das Tag <call> gibt an, welche API-Methode mithilfe ihres Methodenattributs aufgerufen wird. In diesem Beispiel lautet die API-Methode exportData. Darüber hinaus ist callerName ein erforderliches Attribut im Tag <call>. Sie identifiziert Ihre Client-Anwendung für das System und wird bei der Fehlerbehebung und Protokollierung verwendet.

Jede API-Methode muss den den aufrufenden Benutzer authentifizieren. Dies geschieht in der Regel durch die Angabe eines Anmeldenamens und eines Kennworts. Andere Attribute können hier angegeben werden. Weitere Details zu Zugangsdaten finden Sie in der Dokumentation der einzelnen API-Funktionen.

Einige API-Methoden erfordern zusätzliche Daten in der Anforderung. Beispielsweise erfordert die Methode exportData einige Kriterien, die beschreiben, welche Zeitperioden, Konten, Ebenen usw. beim Abrufen der Daten verwendet werden sollen. Dieser Teil der Anforderung variiert von Methode zu Methode.

Dies ist das abschließende Tag für das Aufruf-Tag in Zeile 2.

Die Antwort

Jede Antwort von einer API-Methode hat die folgende Struktur:


     <?xml version='1.0' encoding='UTF-8'?>
     <response success="true">
       <messages>
          <message key="modeled-import-success">Personnel import successful. Rows imported: 100</message>
       </messages>
       <output>
         ... method output ...
       </output>
     </response>

Hier ist eine Beschreibung der relevanten Positionen:

Ähnlich wie bei der Anforderung gibt diese Zeile an, dass die nachfolgenden Daten als XML formatiert und in UTF-8 codiert sind.

Jede Antwort ist in ein Tag <response> eingeschlossen. Wenn die Anforderung erfolgreich war, wird das Attribut „ Success“ im Antwort-Tag auf „true“ gesetzt. Wenn die Anforderung nicht erfolgreich war, wird das Erfolgsattribut auf „false“ gesetzt.

Viele API-Aufrufe geben diesen optionalen <messages> -Block zurück, der eine Liste der vom Server generierten Meldungen enthält. Dieser Block wird möglicherweise nicht angezeigt, wenn der Server als Antwort auf den Aufruf keine Nachrichten zurückgeben konnte. Fehlermeldungen werden immer innerhalb des Nachrichtenblocks angezeigt.

Jede Nachricht innerhalb des Nachrichtenblocks hat ein Schlüsselattribut, das die Art der übermittelten Nachricht angibt. Das Nachrichten-Tag enthält auch den Text der Nachricht vom Server, einschließlich aller Rückgabewerte, Statuswerte oder anderer eigenständiger Metadaten zum erfolgreichen oder fehlgeschlagenen Antrag. Eine Antwort kann eine unbegrenzte Anzahl von Nachrichten-Tags enthalten.

Das Tag der Abschlussnachricht.

Die tatsächliche Ausgabe des API-Methodenaufrufs, falls eine zurückgegeben wird, wird in ein Tag <output> eingeschlossen.

Die tatsächliche Ausgabe des API-Methodenaufrufs wird hier angezeigt. Diese Ausgabe hängt davon ab, welche Methode aufgerufen wurde.

Abschluss-Ausgabe-Tag.

Mit dem Antwort-Tag für den Abschluss.