Inhaltselemente
Sobald Sie einen Inhaltstyp definiert haben, können Sie Elemente dieses Typs hinzufügen - die sogenannten Inhaltselemente.
Das JSON eines Inhaltselements hängt von seinem Inhaltstyp ab. Um zu sehen, welche Felder ein Inhaltstyp hat, öffnen Sie die Swagger-Oberfläche und authentifizieren Sie sich mit einem Zugangstoken: Die Swagger-Oberfläche listet die Operationen für Elemente eines bestimmten Typs dann für jeden Inhaltstyp noch einmal auf (z.B. /api/content/building), zusammen mit einem Modell <contenttypename>ContentItemDto seiner Felder. Siehe Operationen und Modelle je Inhaltstyp.
1. Abfrage von Inhaltselementen
Ruft die Inhaltselemente aller prüfbaren Inhaltstypen (Inhaltstypen mit "canBeInspected": true) ab, unabhängig von ihrem Typ.
Elemente anderer Inhaltstypen liefert dieser Endpunkt nicht; verwenden Sie dafür den Endpunkt für einen bestimmten Typ.
Erforderliche Berechtigung: ContentItems.List
Beispiel:
GET https://dev.iclportal.com/api/content?$inlinecount=allpages&$top=20 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Die Antwort ist ein JSON-Array mit Inhaltselementen:
{
"result": {
"__count": 2932,
"results": [
{
"bezeichnung": "Wien, Hansonstrasse 23",
"adresse": "Hansonstrasse 23",
"ort": "Wien",
"nummer": "GB-00012",
"plz": "1100",
"contentItemId": "18c7a93c-0865-4922-af34-31d112e4d2ac",
"externalId": "OPTI-Q1",
"lastModificationTime": "2020-10-09T13:19:29.673Z",
"isDeleted": false,
"creatorUserId": null,
"creatorUser": null,
"lastModifierUserId": 2,
"lastModifierUser": "Antoine Gadget",
"title": "Wien, Hansonstrasse 23"
},
...
]
},
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
Mit den OData v3-Optionen $top, $skip und $inlinecount können Sie durch die Ergebnisse blättern.
Da dieser Endpunkt Elemente aller Typen liefert, ist das Filtern stark eingeschränkt. Es wird nur ein einzelner Filterausdruck unterstützt:
substringof,startswithoderendswithaufTitleoderExternalId- alle drei liefern die Elemente, deren Titel bzw. externe ID den angegebenen Text enthältId eq '<contentItemId>', um das Element mit diesercontentItemIdabzurufen
Jeder andere Filterausdruck (andere Felder, Verknüpfungen mit and/or) wird stillschweigend ignoriert.
Benutzerdefinierte Felder werden zwar vom Endpunkt zurückgegeben, können aber nicht zum Filtern verwendet werden.
Eine Abfrage, die nicht verarbeitet werden kann, liefert 400 Bad Request.
Beispiel:
GET https://dev.iclportal.com/api/content?$filter=substringof('hansonstrasse',tolower(Title))&$inlinecount=allpages&$top=20 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Beachten Sie, dass die Eigenschaft Title in der Abfragezeichenfolge in Großbuchstaben geschrieben wird. Dies ist eine Anforderung von OData v3.
Die Antwort ist ein JSON-Array mit Inhaltselementen:
{
"result": {
"__count": 1,
"results": [
{
"bezeichnung": "Wien, Hansonstrasse 23",
"adresse": "Hansonstrasse 23",
"ort": "Wien",
"nummer": "GB-00012",
"plz": "1100",
"contentItemId": "18c7a93c-0865-4922-af34-31d112e4d2ac",
"externalId": "OPTI-Q1",
"lastModificationTime": "2020-10-09T13:19:29.673Z",
"isDeleted": false,
"creatorUserId": null,
"creatorUser": null,
"lastModifierUserId": 2,
"lastModifierUser": "Antoine Gadget",
"title": "Wien, Hansonstrasse 23"
}
]
},
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
2. Abfrage von Inhaltselementen eines bestimmten Typs
Ruft alle Inhaltselemente eines bestimmten Typs ab.
Erforderliche Berechtigung: ContentItems.List
Beispiel:
GET https://dev.iclportal.com/api/content/building?$inlinecount=allpages&$top=20 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Die Antwort ist ein JSON-Array mit Inhaltselementen:
{
"result": {
"__count": 2932,
"results": [
{
"bezeichnung": "Wien, Hansonstrasse 23",
"adresse": "Hansonstrasse 23",
"ort": "Wien",
"nummer": "GB-00012",
"plz": "1100",
"contentItemId": "18c7a93c-0865-4922-af34-31d112e4d2ac",
"externalId": "OPTI-Q1",
"lastModificationTime": "2020-10-09T13:19:29.673Z",
"isDeleted": false,
"creatorUserId": null,
"creatorUser": null,
"lastModifierUserId": 2,
"lastModifierUser": "Antoine Gadget",
"title": "Wien, Hansonstrasse 23"
},
...
]
},
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
Sie können die API mit der OData v3 Abfragesyntax abfragen ($filter, $orderby, $top, $skip, $inlinecount).
Sie können nach den benutzerdefinierten Feldern des Inhaltstyps sowie nach den internen Feldern ContentItemId, ExternalId, IsDeleted, LastModificationTime und InspectionId filtern und sortieren.
Title kann nur verwendet werden, wenn der Inhaltstyp ein Feld namens title definiert.
Eine Abfrage, die nicht verarbeitet werden kann oder ein unbekanntes Feld bzw. einen nicht unterstützten Operator verwendet, liefert 400 Bad Request.
Abfragen, die nach nicht indizierten benutzerdefinierten Feldern (d.h. ohne "isIndexed": true) filtern oder sortieren, unterliegen einer Ratenbeschränkung: Wurde dieselbe Abfrage eine bestimmte Anzahl von Malen gesendet, wird sie mit einem Fehler abgewiesen.
Siehe Ratenbeschränkung für Abfragen von nicht indizierten Feldern.
Beispiel:
GET https://dev.iclportal.com/api/content/building?$filter=substringof('hansonstrasse',tolower(Adresse))&$inlinecount=allpages&$top=20 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Beachten Sie, dass die Eigenschaft Adresse in der Abfragezeichenfolge in Großbuchstaben geschrieben wird, obwohl sie im Inhaltstyp kleingeschrieben definiert werden muss. Dies ist eine Anforderung von OData v3.
Die Antwort ist ein JSON-Array mit Inhaltselementen:
{
"result": {
"__count": 1,
"results": [
{
"bezeichnung": "Wien, Hansonstrasse 23",
"adresse": "Hansonstrasse 23",
"ort": "Wien",
"nummer": "GB-00012",
"plz": "1100",
"contentItemId": "18c7a93c-0865-4922-af34-31d112e4d2ac",
"externalId": "OPTI-Q1",
"lastModificationTime": "2020-10-09T13:19:29.673Z",
"isDeleted": false,
"creatorUserId": null,
"creatorUser": null,
"lastModifierUserId": 2,
"lastModifierUser": "Antoine Gadget",
"title": "Wien, Hansonstrasse 23"
}
]
},
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
Um die Abfrage zu erstellen, können Sie einfach die iCL Portal Datentabelle des jeweiligen Inhaltstyps verwenden und dort die Sortierungen und Filter angeben. Verwenden Sie dann die Entwicklungswerkzeuge Ihres Browsers, um die erstellte Abfrage auf der Registerkarte Netzwerk zu betrachten:
3. Erstellen eines Inhaltsartikels
Erzeugt ein neues Inhaltselement. Beachten Sie, dass nur erforderliche Felder angegeben werden müssen; das Titelfeld des Inhaltstyps ist immer erforderlich.
Wenn Sie ein Element erstellen, das über ein Inhaltsfeld vom Typ ContentItem auf ein anderes verweist (z.B. Sie erstellen ein Gebäude, das zu einer Site gehört), können Sie diese Site entweder über ihre contentItemId oder externalId angeben.
Sie können die contentItemId des neuen Elements auch selbst vorgeben. Existiert bereits ein Element mit dieser contentItemId, schlägt die Anfrage fehl.
Erforderliche Berechtigung: ContentItems.Create
Beispiel
POST https://dev.iclportal.com/api/content/building
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
{
"externalId":"HG",
"buildingname":"HG10223",
"strasse":"Hansongasse 23",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien"
}
Die Antwort hat den Statuscode 201 Created; ihr Location-Header enthält die URL des neuen Elements (z.B. https://dev.iclportal.com/api/content/building/39d83715-b7d0-4a1e-88a7-bed24d5ab8a0).
Der Antwortinhalt ist das gesendete JSON-Objekt, ergänzt um die internen Felder.
{
"buildingname":"HG10223",
"strasse":"Hansongasse 23",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien",
"contentItemId":"39d83715-b7d0-4a1e-88a7-bed24d5ab8a0",
"_id":"a8218840-e764-46b7-a289-9e52b65cff66",
"externalId":"HG",
"lastModificationTime":"2023-03-14T12:42:41.1951367Z",
"isDeleted":false,
"creatorUserId":2,
"creatorUser":"Antoine Gadget",
"lastModifierUserId":null,
"lastModifierUser":null
}
Ist das Element ungültig (z.B. fehlt das Titelfeld, hat ein Attribut kein entsprechendes Feld im Inhaltstyp oder wird die externalId bereits von einem anderen Element verwendet), wird nichts gespeichert und die Antwort ist ein Fehlerobjekt ("success": false, HTTP-Status 500), das das Problem in error.message beschreibt.
4. Abrufen eines Inhaltselements
Durch Angabe der internen _id, contentItemId oder externalId können Sie ein Element abrufen.
Erforderliche Berechtigung: ContentItems.View
Die folgenden Anfragen liefern alle das gleiche Ergebnis:
Beispiel: Verwendung der internen _id
GET https://dev.iclportal.com/api/content/building/a8218840-e764-46b7-a289-9e52b65cff66
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Beispiel: Verwendung der contentItemId
GET https://dev.iclportal.com/api/content/building/39d83715-b7d0-4a1e-88a7-bed24d5ab8a0
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Beispiel: Verwendung der externalId
GET https://dev.iclportal.com/api/content/building/HG
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Rückgabe:
{
"buildingname":"HG10223",
"strasse":"Hansongasse 23",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien",
"contentItemId":"39d83715-b7d0-4a1e-88a7-bed24d5ab8a0",
"_id":"a8218840-e764-46b7-a289-9e52b65cff66",
"externalId":"HG",
"lastModificationTime":"2023-03-14T12:42:41.1951367Z",
"isDeleted":false,
"creatorUserId":2,
"creatorUser":"Antoine Gadget",
"lastModifierUserId":null,
"lastModifierUser":null
}
Passt kein Element, ist die Antwort 404 Not Found. Passt die ID auf mehr als ein Element (z.B. weil mehrere Elemente dieselbe externalId verwenden), ist die Antwort 400 Bad Request und listet die passenden Elemente auf; verwenden Sie stattdessen deren contentItemId oder _id.
5. Ersetzen eines Inhaltselements
Ersetzt ein bestehendes Inhaltselement vollständig mit den übergebenen Daten. Alle Felder müssen in der Anfrage enthalten sein — Felder, die nicht mitgesendet werden, werden aus dem Element entfernt.
Wenn Sie ein Element erstellen, das über ein Inhaltsfeld vom Typ ContentItem auf ein anderes verweist (z.B. Sie erstellen ein Gebäude, das zu einer Site gehört), können Sie diese Site entweder über ihre contentItemId oder externalId angeben.
Sie können die interne _id, contentItemId oder externalId verwenden, um ein Element zu identifizieren.
Erforderliche Berechtigung: ContentItems.Edit
Dies ist eine vollständige Ersetzungsoperation. Alle Attribute, die nicht in der Anfrage enthalten sind, werden aus dem Artikel gelöscht! Wenn Sie nur einzelne Felder aktualisieren möchten, verwenden Sie stattdessen den PATCH-Endpunkt.
Beispiel - Verwendung von externalId, aber Weglassen des Feldes strasse
PUT https://dev.iclportal.com/api/content/building/HG
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
{
"externalId":"HG",
"buildingname":"HG10223",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien"
}
Bei Erfolg ist die Antwort 200 OK ohne Inhalt. Existiert das Element nicht, wird 404 Not Found geliefert; ein ungültiges Element führt zu einem Fehlerobjekt wie beim Erstellen eines Elements beschrieben.
Beachten Sie, dass das Feld strasse in der Anfrage ausgelassen wurde und daher aus dem Objekt entfernt wird. Ein anschließendes Abrufen des Elements liefert:
{
"buildingname":"HG10223",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien",
"contentItemId":"39d83715-b7d0-4a1e-88a7-bed24d5ab8a0",
"_id":"a8218840-e764-46b7-a289-9e52b65cff66",
"externalId":"HG",
"lastModificationTime":"2023-03-14T12:42:41.1951367Z",
"isDeleted":false,
"creatorUserId":2,
"creatorUser":"Antoine Gadget",
"lastModifierUserId":null,
"lastModifierUser":null
}
6. Teilweises Aktualisieren eines Inhaltselements
Aktualisiert nur die angegebenen Felder eines bestehenden Inhaltselements. Alle Felder, die nicht in der Anfrage enthalten sind, bleiben unverändert.
Sie können die interne _id, contentItemId oder externalId verwenden, um ein Element zu identifizieren.
Erforderliche Berechtigung: ContentItems.Edit
Im Gegensatz zu PUT, das das gesamte Element ersetzt, ändert PATCH nur die mitgesendeten Felder. Damit eignet es sich ideal zum Aktualisieren einzelner Felder, ohne das vollständige Element erneut senden zu müssen.
Beispiel - Verwendung von externalId, um nur das Feld strasse zu aktualisieren
PATCH https://dev.iclportal.com/api/content/building/HG
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
{
"strasse":"Karlsplatz 1"
}
Das Feld strasse wird auf den neuen Wert aktualisiert. Alle anderen Felder bleiben unverändert.
Um ein Feld zu leeren, setzen Sie es explizit auf null:
PATCH https://dev.iclportal.com/api/content/building/HG
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
{
"stiege": null
}
Bei Erfolg ist die Antwort 200 OK ohne Inhalt. Ist der Anfrageinhalt kein JSON-Objekt, ist die Antwort 400 Bad Request; existiert das Element nicht, 404 Not Found.
7. Löschen eines Inhaltselements
Löscht ein bestehendes Inhaltselement.
Sie können die interne _id, contentItemId oder externalId verwenden, um ein Element zu identifizieren.
Erforderliche Berechtigung: ContentItems.Delete
Inhaltselemente werden nie wirklich aus der Datenbank gelöscht, um Datenverluste zu vermeiden. Stattdessen wird ihre Spalte IsDeleted auf true gesetzt und sie werden aus allen zukünftigen Anfragen herausgefiltert.
Beispiel - Verwendung von externalId
DELETE https://dev.iclportal.com/api/content/building/HG
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Die Antwort wird leer sein und den entsprechenden Statuscode enthalten:
- 200 OK für Erfolg,
- 400 Fehlerhafte Anfrage, falls Sie etwas falsch gemacht haben
- 404 Nicht gefunden, falls das Objekt nicht existiert oder zuvor gelöscht wurde
8. Hinzufügen/Aktualisieren mehrerer Inhaltselemente auf einmal
Dieser Endpunkt ermöglicht es Ihnen, mehrere Inhaltselemente in einem Stapel hinzuzufügen oder zu aktualisieren.
Jedes Element wird mit den bestehenden Elementen des Inhaltstyps abgeglichen: Ein Element, das eine contentItemId enthält, wird über diese identifiziert, jedes andere Element über seine externalId.
Wenn ein Element gefunden wird, wird es aktualisiert. Wenn nicht, wird ein neues Element erstellt (mit der angegebenen contentItemId, falls vorhanden).
Erforderliche Berechtigung: ContentItems.Edit
Wenn ein vorhandenes Element gefunden wird, werden nur die Attribute aktualisiert, die in der Anfrage enthalten sind. Alle anderen Felder behalten ihren aktuellen Wert - auch Bilder und Pläne. Um ein Feld zu leeren, setzen Sie es explizit auf null.
Wenn ein Element Validierungsfehler aufweist, wird der gesamte Stapel zurückgesetzt und kein Element hinzugefügt oder aktualisiert.
Wenn ein Element ein anderes über ein Inhaltsfeld vom Typ ContentItem referenziert (z.B. wenn Sie ein Gebäude erstellen, das zu einer Site gehört), können Sie diese Site entweder über ihre contentItemId oder externalId angeben.
Beispiel
POST https://dev.iclportal.com/api/content/building/batch
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
[
{
"externalId":"HG",
"buildingname":"HG10223",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien"
},
{
"externalId":"LHS101",
"buildingname":"LANHS101",
"stiege":"10",
"strasse":"Landstraßer Hauptstraße",
"stock":1,
"topnr":"GO11",
"plz":"1030",
"ort":"Wien"
}
]
Wurden alle Elemente gespeichert, ist die Antwort 200 OK mit folgendem Inhalt (beide Listen sind immer leer):
{
"errored": [],
"succeeded": []
}
Ist ein Element ungültig, wird nichts gespeichert und die Antwort ist ein Fehlerobjekt (HTTP-Status 500), dessen error.message die Validierungsfehler auflistet:
{
"targetUrl": null,
"result": null,
"success": false,
"error": {
"code": 0,
"message": "The field 'buildingname' is used as title field and thus required. You must provide a value",
"details": null,
"validationErrors": null
},
"unAuthorizedRequest": false,
"__abp": true
}
Ist der Anfrageinhalt kein JSON-Array, ist die Antwort 400 Bad Request.
9. Hinzufügen/Aktualisieren mehrerer Inhaltselemente auf einmal - Fehler ignorieren
Dieser Endpunkt ermöglicht es Ihnen, mehrere Inhaltselemente in einem Stapel hinzuzufügen oder zu aktualisieren.
Die Elemente werden wie beim Stapel-Endpunkt abgeglichen: über ihre contentItemId, falls angegeben, sonst über ihre externalId. Falls ein Element gefunden wird, wird es aktualisiert. Wenn nicht, wird ein neues Element erstellt.
Erforderliche Berechtigung: ContentItems.Edit
Wenn ein vorhandenes Element gefunden wird, werden nur die Attribute aktualisiert, die in der Anfrage enthalten sind. Alle anderen Felder behalten ihren aktuellen Wert - auch Bilder und Pläne. Um ein Feld zu leeren, setzen Sie es explizit auf null.
Im Falle eines Fehlers wird die Operation fortgesetzt. Alle gültigen Einträge werden gespeichert, nur die ungültigen werden übersprungen.
Dieser Endpunkt ist für Integrationsszenarien mit Tools wie SSIS oder Azure Data Factory gedacht. Im Falle eines Fehlers können Sie diesen z.B. per E-Mail an den Benutzer im Quellsystem zurücksenden, sodass er die Probleme mit den fehlgeschlagenen Elementen beheben kann
Wenn ein Element über ein Inhaltsfeld vom Typ ContentItem auf ein anderes verweist (z.B. wenn Sie ein Gebäude erstellen, das zu einer Site gehört), können Sie diese Site entweder über ihre contentItemId oder externalId angeben.
Beispiel
POST https://dev.iclportal.com/api/content/building/batchforce
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
[
{
"externalId":"HG11",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien"
},
{
"externalId":"LHS101",
"buildingname":"LANHS101",
"stiege":"10",
"strasse":"Landstraßer Hauptstraße",
"stock":1,
"topnr":"GO11",
"plz":"1030",
"ort":"Wien"
}
]
Wurden alle Elemente gespeichert, ist die Antwort 200 OK mit leeren Listen: {"errored":[],"succeeded":[]}.
Ist mindestens ein Element ungültig, ist die Antwort 400 Bad Request und listet die ungültigen Elemente in errored auf - die gültigen Elemente werden trotzdem gespeichert.
Jedes ungültige Element wird über seine contentItemId identifiziert, falls diese in der Anfrage angegeben wurde, sonst über seine externalId (in beiden Fällen im Attribut externalId).
Die Liste succeeded ist immer leer.
{
"errored": [
{
"externalId": "HG11",
"error": "The field 'buildingname' is used as title field and thus required. You must provide a value"
}
],
"succeeded": []
}
Ist der Anfrageinhalt kein JSON-Array, ist die Antwort 400 Bad Request ohne Inhalt.
10. Änderungen von Elementen aller Typen abrufen
Dieser Endpunkt gibt alle Inhaltselemente unabhängig von ihrem Typ zurück, die seit einem bestimmten Zeitpunkt geändert wurden.
Dieser Zeitpunkt wird als changeToken bezeichnet und als Abfrageargument angegeben.
Wenn Sie diesen changeToken weglassen (oder 0 übergeben), erhalten Sie im Wesentlichen alle Inhaltselemente.
Erforderliche Berechtigung: ContentItems.View
Dieser Endpunkt ist für Integrationsszenarien gedacht, bei denen Sie Inhaltselemente von iCL Portal mit einem externen System Ihrer Wahl synchronisieren müssen. Um so effizient wie möglich zu sein, ermöglicht er Ihnen, inkrementelle Änderungen zu erhalten, sodass Sie nicht eine ständig wachsende Liste von Objekten durchgehen müssen, bis Sie auf Timeouts stoßen.
Das folgende Beispiel zeigt die erste Anfrage (ohne den changeToken)
GET https://dev.iclportal.com/api/content/getchanges
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Die Antwort enthält alle Elemente, die seit diesem Zeitpunkt geändert wurden
und enthält einen nextChangeToken, der verwendet werden kann, um die nächste Seite von Änderungen zu erhalten.
Alternativ können Sie auch den nextLink verwenden.
Beachten Sie, dass die Ergebnismenge standardmäßig auf 500 Einträge pro Seite begrenzt ist (die Seitengröße kann in der Serverkonfiguration über Api.GetChanges.PageSize geändert werden). Sie müssen die Daten durchblättern, wenn Sie mehr Einträge/Änderungen haben.
{
"result": {
"results": [
{
"bezeichnung": "LSHS101-1030",
"adresse": "Landstraßer Hauptstraße 101",
"ort": "Wien",
"nummer": "101",
"_id": "0b6c1f0e-5d0c-4c1e-9a37-3d3a3c1f2b11",
"contentItemId": "683a34a9-b832-490a-8ab1-5d98aafc7d7f",
"externalId": "LSHS101-1030",
"lastModificationTime": "2018-11-20T15:21:43.767Z",
"isDeleted": true,
"inspectionId": null,
"$type": "gebaude"
},
{
"beschreibung": "Der DHL Bote findet den Eingang zu Opti-Q (Altstiege 2) nie",
"objektid": "683a34a9-b832-490a-8ab1-5d98aafc7d7f",
"gewerk": "Paketdienst",
"status": 0,
"frist": "2018-11-29T23:00:00Z",
"_id": "5f1d2a77-8c3e-4b0a-a1d2-6e4f9b8c7a21",
"contentItemId": "f66ba90c-819d-40c4-acdc-984220ba04b0",
"externalId": null,
"lastModificationTime": "2018-12-11T15:55:05.963Z",
"isDeleted": true,
"inspectionId": null,
"$type": "mangel"
},
...
],
"nextChangeToken": "AAAAAAADRF8",
"nextLink": "https://testportal.opti-q.com/api/content/getchanges?changeToken=AAAAAAADRF8"
},
"success": true,
"__abp": true
}
Da der Inhaltstyp nicht angegeben ist, enthält jedes Ergebnis ein Attribut $type, das den Inhaltstyp des Elements angibt.
Sobald Sie die letzte Seite erreicht haben, ist das Array results leer und der nextChangeToken wird sich nicht mehr ändern.
Schlägt die Anfrage fehl (z.B. wegen eines ungültigen changeToken oder einer fehlenden Berechtigung), ist die Antwort 400 Bad Request.
Da dieser Endpunkt für Synchronisierungsszenarien gedacht ist, gibt er auch gelöschte Objekte zurück. In diesem Fall wird ihr Attribut isDeleted auf true gesetzt.
11. Änderungen von Elementen eines bestimmten Typs abrufen
Dieser Endpunkt gibt alle Inhaltselemente des angegebenen Inhaltstyps zurück, die seit einem bestimmten Zeitpunkt geändert wurden.
Dieser Zeitpunkt wird als changeToken bezeichnet und als Abfrageargument angegeben.
Wenn Sie diesen changeToken weglassen (oder 0 übergeben), erhalten Sie im Wesentlichen alle Inhaltselemente dieses Typs.
Erforderliche Berechtigung: ContentItems.View
Dieser Endpunkt ist für Integrationsszenarien gedacht, bei denen Sie Inhaltselemente von iCL Portal mit einem externen System Ihrer Wahl synchronisieren müssen. Um so effizient wie möglich zu sein, ermöglicht er Ihnen, inkrementelle Änderungen zu erhalten, sodass Sie nicht eine ständig wachsende Liste von Objekten durchgehen müssen, bis Sie auf Timeouts stoßen.
Das folgende Beispiel zeigt die erste Anfrage (ohne den changeToken)
GET https://dev.iclportal.com/api/content/building/getchanges
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
Die Antwort enthält alle Elemente, die seit diesem Zeitpunkt geändert wurden
und enthält einen nextChangeToken, der verwendet werden kann, um die nächste Seite von Änderungen zu erhalten.
Alternativ können Sie auch den nextLink verwenden.
Beachten Sie, dass die Ergebnismenge standardmäßig auf 500 Einträge pro Seite begrenzt ist (die Seitengröße kann in der Serverkonfiguration über Api.GetChanges.PageSize geändert werden). Sie müssen die Daten durchblättern, wenn Sie mehr Einträge/Änderungen haben.
{
"result": {
"results": [
{
"buildingname": "LSHS101-1030",
"strasse": "Landstraßer Hauptstraße 101",
"ort": "Wien",
"topnr": "101",
"_id": "0b6c1f0e-5d0c-4c1e-9a37-3d3a3c1f2b11",
"contentItemId": "683a34a9-b832-490a-8ab1-5d98aafc7d7f",
"externalId": "LSHS101-1030",
"lastModificationTime": "2018-11-20T15:21:43.767Z",
"isDeleted": true,
"inspectionId": null
},
{
"buildingname":"HG10223",
"strasse":"Hansongasse 23",
"stiege":"1",
"stock":4,
"topnr":"43",
"plz":"1010",
"ort":"Wien",
"_id":"a8218840-e764-46b7-a289-9e52b65cff66",
"contentItemId":"39d83715-b7d0-4a1e-88a7-bed24d5ab8a0",
"externalId":"HG",
"lastModificationTime":"2023-03-14T12:42:41.1951367Z",
"isDeleted":false,
"inspectionId": null
},
...
],
"nextChangeToken": "AAAAAAADRF8",
"nextLink": "https://testportal.opti-q.com/api/content/building/getchanges?changeToken=AAAAAAADRF8"
},
"success": true,
"__abp": true
}
Da der Inhaltstyp explizit angegeben wird, enthalten die Elemente nicht das Attribut $type.
Wenn Sie die letzte Seite erreicht haben, wird das Array results leer sein und der nextChangeToken wird sich nicht mehr ändern.
Schlägt die Anfrage fehl (z.B. weil der Inhaltstyp nicht existiert, der changeToken ungültig ist oder die Berechtigung fehlt), ist die Antwort 400 Bad Request.
Da dieser Endpunkt für Synchronisierungsszenarien gedacht ist, gibt er auch gelöschte Objekte zurück. In diesem Fall wird ihr Attribut isDeleted auf true gesetzt.
Da es keine weiteren Änderungen mehr gibt, gibt das System einfach die letzte verfügbare Änderung zurück, was in der Regel genau der gleiche Änderungs-Token ist, den wir gerade in der Anfrage verwendet haben.
Sie können jedoch diesen Mechanismus nutzen, um direkt zur letzten Seite der geänderten Inhaltselemente zu gelangen, indem Sie den höchstmöglichen Änderungs-Token __________8 verwenden.
Dies ist praktisch, wenn Sie nur die Änderungen von jetzt abrufen wollen und nicht alle historischen Änderungen durchgehen wollen.
12. Herunterladen einer Excel-Vorlage
Mit diesem Endpunkt können Sie eine Excel-Arbeitsmappe herunterladen, mit der Sie Inhaltselemente in das iCL Portal importieren können. Füllen Sie dazu die Arbeitsmappe aus und ziehen Sie sie per Drag-and-Drop in ein beliebiges Inhaltselement-Datentraster, oder laden Sie sie über den Import-Endpunkt hoch.
Erforderliche Berechtigung: ContentItems.View
Beispiel
GET https://dev.iclportal.com/api/content/building/template/excel
Authorization: Bearer ..the auth_token...
Die Antwort ist die Datei building_import_template.xlsx (der Name des Inhaltstyps gefolgt von _import_template.xlsx).
Falls eines der importierten Elemente bereits existiert, werden die Elementeigenschaften mit den Werten aus der Importdatei aktualisiert. Wenn eine Spalte nicht angegeben ist, wird das Feld nicht aus dem Artikel gelöscht, sondern einfach nicht berührt. Auf diese Weise können Sie nur bestimmte Felder eines Inhaltsartikels aktualisieren, ohne etwas anderes zu löschen, das nicht angegeben ist!
Beachten Sie, dass jede Zeile einen Wert in der Spalte ExternalId oder Id (die contentItemId) haben muss.
Damit wird sichergestellt, dass Benutzer nicht versehentlich dieselbe Excel Arbeitsmappe mehrfach hochladen und dadurch doppelte Daten erhalten!
13. Importieren von Inhaltselementen aus Excel
Lädt eine ausgefüllte Excel-Arbeitsmappe (erstellt über die Excel-Vorlage oder den Excel-Export) hoch, um Inhaltselemente zu importieren.
Die Arbeitsmappe wird als multipart/form-data gesendet. Jedes Blatt der Arbeitsmappe wird in den gleichnamigen Inhaltstyp importiert, eine Arbeitsmappe kann also Elemente mehrerer Inhaltstypen enthalten.
Um auch Bilder zu importieren, laden Sie eine .zip-Datei mit der Arbeitsmappe und den Bildern hoch, wie sie der Excel-Export mit includeImages=true erstellt.
Erforderliche Berechtigungen: ContentItems.Create, ContentItems.Edit und ContentItems.Delete (alle drei)
Beispiel
POST https://dev.iclportal.com/api/content/import
Content-Type: multipart/form-data; boundary=----boundary
Authorization: Bearer ..the auth_token...
------boundary
Content-Disposition: form-data; name="file"; filename="building_import_template.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
...file content...
------boundary--
Die Antwort ist 200 OK, sobald die Datei hochgeladen wurde. Der Import selbst läuft im Hintergrund:
Er speichert die Elemente nur, wenn die gesamte Arbeitsmappe gültig ist. Andernfalls werden die Fehler als Kommentare in die Arbeitsmappe geschrieben und kein Element wird importiert.
Das Ergebnis des Imports wird in der Benutzeroberfläche von iCL Portal angezeigt; die API-Antwort enthält es nicht.
14. Exportieren von Inhaltselementen nach Excel
Exportiert die Inhaltselemente eines Inhaltstyps in eine Excel-Arbeitsmappe, die bearbeitet und wieder importiert werden kann.
Erforderliche Berechtigung: ContentItems.Export
| Parameter | Beschreibung |
|---|---|
includeImages | Erforderlich. false liefert eine Excel-Arbeitsmappe (.xlsx); true liefert eine .zip-Datei, die die Arbeitsmappe und die Bilder der Elemente enthält. |
Sie können die exportierten Elemente mit denselben OData v3-Optionen $filter und $orderby einschränken und sortieren wie bei der Abfrage von Inhaltselementen eines bestimmten Typs.
Beispiel
GET https://dev.iclportal.com/api/content/building/export?includeImages=false
Authorization: Bearer ..the auth_token...
Die Antwort ist die Datei building.xlsx (bzw. building.zip bei includeImages=true).
15. Änderungen seit einem Datum abrufen (veraltet)
GET /api/contentsync/{contentTypeName}/{dateStr} ist veraltet. Verwenden Sie stattdessen Änderungen von Elementen eines bestimmten Typs abrufen.
Liefert die Inhaltselemente eines Inhaltstyps - einschließlich gelöschter Elemente -, die seit dem Datum dateStr geändert wurden (in UTC, Format yyyyMMddTHHmmss, z.B. 20200112T103055).
Die Antwort hat dasselbe Format wie bei der Abfrage von Inhaltselementen eines bestimmten Typs.
Erforderliche Berechtigung: ContentItems.List