Daten per OData API zur Verfügung stellen
Gültig ab OCT Version 5.10
Beschreibt die Bereitstellung von Daten aus der OCT Datenbank im OData Format. Das OData Format kann von vielen Drittprogrammen standardmäßig gelesen und verarbeitet werden (z.B. Excel, PowerBI, Tagetik).
1. Voraussetzungen
In einer OCT Datenbank unter “Administration” → “Einstellungen” → “OData” muss ein Benutzername und ein Passwort für den Zugriff auf die OData API festgelegt werden.
2. Erstellen eines OData Endpunkts zum Datenabruf
Für jede SQL Server Prozedur im “odata” Schema der OCT Datenbank wird automatisch ein OData Endpunkt erzeugt.
Dementsprechend muss man zum Erstellen eines neuen OData Endpunkts nur eine passende Prozedur erstellen.
2.1. Grundsätzliche Bedingungen
die Prozedur muss im Schema “odata” erstellt sein
der Name der Prozedur darf keine Sonderzeichen enthalten
die Prozedur muss den Parameter @Username vom Typ NVARCHAR enthalten
die Prozedur muss genau eine Ergebnismenge zurückgeben
2.2. Beispielprozedur Liste der Mandanten “odata.Mandanten”
DROP PROCEDURE IF EXISTS odata.Mandanten;
GO
CREATE PROCEDURE odata.Mandanten
@Username NVARCHAR(255) = NULL
AS
BEGIN
BEGIN TRY
-- Logging
DECLARE @TimestampCall DATETIME = GETUTCDATE();
DECLARE @ProcedureName NVARCHAR(255) = OBJECT_SCHEMA_NAME(@@PROCID) + N'.' + OBJECT_NAME(@@PROCID);
DECLARE @AffectedRows INT = 0;
DECLARE @ResultCode INT = 501;
DECLARE @Comment NVARCHAR(4000) = N'';
DECLARE @ParameterString NVARCHAR(MAX) = N'';
DECLARE @TransactUsername NVARCHAR(255) = N'';
EXEC system.spGET_ParameterString @ParameterString OUTPUT, 1, @Username;
EXEC system.spGET_TransactUsername @TransactUsername OUTPUT, @Username;
-- Return data
SELECT
MandantenID AS MandantenID
, MandantenName AS MandantenName
, COALESCE(Beschreibung, '') AS Beschreibung
, FinanzjahrBeginn AS FinanzjahrBeginn
, COALESCE(Kontorahmen, '') AS Kontorahmen
, Kontenlaenge AS Kontenlaenge
, COALESCE(Waehrung, '') AS Waehrung
FROM result.tFIN_Mandanten;
SET @AffectedRows = @@ROWCOUNT;
SET @ResultCode = 200;
END TRY
BEGIN CATCH
SET @ResultCode = 500;
SET @Comment = ERROR_MESSAGE();
END CATCH;
EXEC dbo.sx_pf_pPOST_API_LogEntry @Username, @TransactUsername, @ProcedureName, @ParameterString, @AffectedRows, @ResultCode, @TimestampCall, @Comment;
IF @ResultCode >= 500
BEGIN
EXEC system.spSEND_Message 'ERROR', @Comment;
END
RETURN @ResultCode;
END;
Der wichtigste Teil der Abfrage sind die Zeilen 21 bis 29, in denen die gewünschten Daten abgefragt werden. Die Befehle davor und danach entsprechen dem Standard-Aufbau einer typischen OCT Prozedur. Grundsätzlich kann die Prozedur beliebig aufgebaut und angepasst werden.
Vorgefertigte OData-Prozeduren für das “FIN” Modul sind im Modul “FIN-ODATA” verfügbar.
3. Aufruf eines OData Endpunkts
Ein OData Endpunkt wird dynamisch anhand der eingespielten Prozeduren im “odata” Schema verfügbar gemacht. Der Aufbau der URL ist folgendermaßen:
http(s)://<Servername>/odata/<Datenbankserver-ID>/<Datenbankname>/<Prozedurname>/octodata
Zum Abruf der Daten wird die GET-Methode verwendet.
Als Authentifizierungsart wird die “Basic” Authentifizierung verwendet. Der Benutzername und das Passwort wurde unter “1. Voraussetzungen” festgelegt.
3.1. Beispiel
Die normale Startseite der OCT Datenbank wird über folgende URL aufgerufen:
https://AppServer01/octsql/octdb/start
Daraus ergibt sich folgender Endpunkt für die Ergebnisse der “odata.Mandanten” Prozedur:
https://AppServer01/odata/octsql/octdb/Mandanten/octodata
3.2. Antwort
Die Antwort erfolgt im standardisierten OData Format.
{
"@odata.context": "https://appserver01/odata/octsql/octdb/Mandanten/$metadata#OctOData",
"value": [
{
"Id": 0,
"MandantenID": "1",
"MandantenName": "Projektbau Leipzig GmbH",
"Beschreibung": "",
"FinanzjahrBeginn": 1,
"Kontorahmen": "",
"Kontenlaenge": 4,
"Waehrung": ""
},
{
"Id": 1,
"MandantenID": "2",
"MandantenName": "Projektbau GmbH & Co.KG",
"Beschreibung": "",
"FinanzjahrBeginn": 1,
"Kontorahmen": "",
"Kontenlaenge": 4,
"Waehrung": ""
},
{
"Id": 2,
"MandantenID": "3",
"MandantenName": "Projektbau Hochbau Leipzig KG",
"Beschreibung": "",
"FinanzjahrBeginn": 1,
"Kontorahmen": "",
"Kontenlaenge": 4,
"Waehrung": ""
}
]
}
Zusätzlich zu den von der Prozedur zurückgegebenen Feldern wird automatisch das Feld “Id” hinzugefügt, das die Datensätze durchgehend nummeriert und einen eindeutigen Schlüssel darstellt.
3.3. Einschränkungen
3.3.1. OpenType Spalten
Aufgrund des dynamischen Aufbaus der OCT OData Schnittstelle werden sämtliche Felder als “OpenType”-Spalten übergeben. Das erfordert bei Drittprogrammen wie z.B. Excel oder PowerBI zusätzliche Einstellungen beim Datenimport (z.B. in Excel die Option “OpenType-Spalten einschließen” aktivieren).
3.3.2. Berechtigungssteuerung
Sämtliche über OData zur Verfügung gestellten Daten sind für alle Benutzer, die Zugriff auf den Benutzernamen und das Passwort haben, zugänglich. Es ist nicht möglich den Umfang der Daten einzuschränken. Daher sollte darauf geachtet werden, dass nur Daten zur Verfügung gestellt werden, auf die alle OData Endanwender Zugriff haben sollten.