Änderungen am API-Format - 15200

Dieses Dokument beschreibt die Unterschiede zwischen den alten und neuen API-Formaten für Anfragen, benutzerdefinierte Module, benutzerdefinierte Zuordnungen und CI-Beziehungen.

Das neue API-Format gilt für Kunden, die auf Build 15200 von ServiceDesk Plus aktualisiert haben. Wir empfehlen, für alle neuen Integrationen die neuen Formate zu verwenden.

Änderungen am Request-API-Format

Wichtige Änderungen im API-Format

Die UDF-Containerfelder wie cm_fields und udf_fields wurden aus den APIs für benutzerdefinierte Module, benutzerdefinierte Zuordnungen und CI-Beziehungen entfernt.
Abwärtskompatibilität wird für APIs von benutzerdefinierten Modulen und CI-Beziehungen unterstützt.
Die Benennungskonventionen für zusätzliche Felder wurden standardisiert:
- Standardmodule:
  - Dieses Update gilt für die folgenden Module: Benutzer, Techniker, CMDB, Release, Projekt, Arbeitsprotokoll, Aufgabe, Bereich, Einrichtung, Lieferant, CI-Typ-Zuordnung, Asset, Support-Gruppen und Abteilung.
  - API-Feldnamen folgen nun dem Format udf_<Benutzereingabe>.
  - Altes Format
    Neues Format
    udf_<field_type>_<user_input> (Beispiel: udf_date_date_of_birth)
    oder
    <field_type>_<user_input> (Beispiel: date_date_of_birth)
    udf_<user input>(Beispiel: udf_date_of_birth)
- Benutzerdefinierte Module und benutzerdefinierte Zuordnungen:
API-Feldnamen sind jetzt vollständig benutzerdefiniert und enthalten nicht das Präfix udf_ . (Beispiel: date_of_birth). Dieses Update gilt nur für Felder, die nach der Migration erstellt wurden.
Felder, die vor der Migration erstellt wurden, bleiben unverändert und behalten ihr aktuelles Verhalten bei.

API für benutzerdefinierte Module

Methode	URL	Altes Format	Neues Format
POST / PUT	/api/v3/cm_test /api/v3/cm_test/<ID>	input_data	input_data
GET	/api/v3/cm_test/<ID>	Beispielantwort:	Beispielantwort:
GET_ALL	/api/v3/cm_test	input_data Beispielantwort:	input_data Beispielantwort:

CI-Beziehungs-API

Methode	URL	Altes Format	Neues Format
POST	/api/v3/cmdb_apache_instance/1/assoc_apache_connected_to_windows_workstations	input_data:	input_data:
GET_ALL	/api/v3/cmdb_apache_instance/1/assoc_apache_connected_to_windows_workstations	Beispielantwort:	Beispielantwort:

Änderungen bei der Abwärtskompatibilität

Die Unterstützung der Abwärtskompatibilität wird ab dem nächsten Feature-Release eingestellt. Wir empfehlen, auf das neue API-Format zu aktualisieren und GlobalConfig entsprechend anzupassen.

Während der Migration werden die API-Namen bestehender benutzerdefinierter Module ("web_tab","configuration","hidden","association" und "published") sowie CI-Beziehungen auf das Attribut paramvalue in GlobalConfig gesetzt.

<GlobalConfig helpdeskid="IT Helpdesk" globalconfigid="GlobalConfig:globalconfigid:120001" category="CM_BACKWARD_COMPATIBILITY" parameter="CM_MODULES_LIST" paramvalue="<entity_api_name>" description="Zur Unterstützung der Abwärtskompatibilität für alte benutzerdefinierte Module"/>

Während der Migration wird wie gezeigt eine Warnmeldung angezeigt:

Nach der Migration wird auf der Detailseite von benutzerdefinierten Modulen und CI-Beziehungen, für die Abwärtskompatibilität bereitgestellt wird, eine Warnmeldung angezeigt.

Benutzerdefinierte Module

CI-Beziehungen

Python-Skripte, benutzerdefinierte Funktionen, benutzerdefinierte Widgets, Feld- und Formularregeln, benutzerdefinierte Skripte und alle externen API-Zugriffe folgen weiterhin dem alten Format, bis die Abwärtskompatibilität entfernt wird, indem der Modul-API-Name aus GlobalConfig entfernt wird.

Nur APIs, die aus der ServiceDesk Plus-Benutzeroberfläche ausgelöst werden, folgen dem neuen Format.

Verwaltung der Abwärtskompatibilität

Um Module zur Unterstützung der Abwärtskompatibilität hinzuzufügen oder daraus zu entfernen, verwenden Sie die folgende Abfrage:

update globalconfig set paramvalue ='<entity_api_name>' where category = 'CM_BACKWARD_COMPATIBILITY';

Änderungen am Requests-API-Format

Dieses Dokument beschreibt die Unterschiede zwischen den alten und neuen API-Formaten für Pflichtfelder, Übergänge, verbundene Status, Genehmigungsstufen, Checklisten und Betriebszeiten-APIs.

Das neue API-Format gilt für Kunden, die auf Build 15200 aktualisiert haben.

Workflow-Erweiterungen

API für Pflichtfelder

	Altes Format	Neues Format
URL	1. api/v3/requests/status_mandatory_fields 2. api/v3/requests/id/status_mandatory_fields	1. api/v3/requests/get_mandatory_fields 2. api/v3/requests/id/get_mandatory_fields
Eingabedaten	{"template_id":5, "status_id":2}	{"template_id":"1","state_id":"2"}
Antwort

Hinweis: Die Felder checklists, tasks, depends_on_requests erscheinen nur dann in der Antwort, wenn sie als Pflichtfelder markiert sind.

API zum Abrufen von Übergängen

	Altes Format	Neues Format
URL	api/v3/requests/id/_get_transitions	api/v3/requests/id/_get_transitions
Antwort

API zum Abrufen verbundener Status

	Altes Format	Neues Format
URL	api/v3/requests/id/_get_connected_statuses	api/v3/requests/id/_get_connected_states
Eingabedaten
Antwort

API zum Abrufen verbundener Knoten

	Altes Format	Neues Format
URL	api/v3/request_lifecycles/<lifecycleid>/get_connected_nodes	/api/v3/request_workflows/<workflowid>/get_connected_nodes
Eingabedaten	{"node_entity_id":0,"module":{"name":"request"}}	{"state_id":0,"module":{"name":"request"}}
Antwort

Antwort der Genehmigungsstufe

Das Feld rule.value in der Antwort der Request-Genehmigungsstufe verwendet die unten gezeigten aktualisierten Werte:

Alter Wert	Neuer Wert
anyone	anyone_approves
all	everyone_approves
first_response	first_response_action

	Altes Format	Neues Format
URL	GET - /requests/{id}/approval_level/{id}	GET - /requests/{id}/approval_level/{id}
ANTWORT

API für Betriebszeiten

Wesentliche Unterschiede auf Entitätsebene

Alter Schlüssel	Neuer Schlüssel	Anmerkungen
site	associated_sites	Die Sitedetails wurden in ein Array-Format geändert.
days_of_operation	days
hours_of_operation	hours
site_type	(entfernt)	Der Sitetyp wird basierend auf dem Wert der globalen Stunden ausgewählt.
day_type	(entfernt)	Der Tagestyp wird basierend auf dem Schlüssel is_standard ausgewählt
exclude_weeks	exception_rules	exclude_weeks wurde aus dem Tagesobjekt entfernt und ein neuer Schlüssel wurde außerhalb davon platziert.

Unterschiede in der Antwort

Verwenden Sie die folgende Legende, um die in der Tabelle verwendeten Farbcodes zu verstehen:
Rot - Entfernte Schlüssel
Gelb - Geänderte Schlüssel
Grün - Neu hinzugefügte Schlüssel

	ALTES FORMAT	NEUES FORMAT
URL	/operational_hours/<id>	/operational_hours/<id>
ANTWORT

Checklisten-Erweiterungen

Wesentliche Unterschiede
In der folgenden Tabelle finden Sie einen schnellen Vergleich der wichtigsten Änderungen, die mit den API-Aktualisierungen eingeführt wurden.
Verwenden Sie die folgende Legende, um die in der Tabelle verwendeten Farbcodes zu verstehen:
Rot - Entfernte Schlüssel
Gelb - Geänderte Schlüssel
Grün - Neu hinzugefügte Schlüssel

API

Alter Endpunkt

Neuer Endpunkt

Alter Schlüssel

Neuer Schlüssel

Abrufen, Hinzufügen, Aktualisieren (Radio-Feld, boolesches Feld, numerisches Feld, einzeiliges Feld)

Alle abrufen, einzeln löschen, massenhaft löschen

/api/v3/additional_fields

/api/v3/item_details

field_id

Änderungen im Eingabeformat der Checklisten-API:

API	API-URL (ALT)	API-URL (NEU)	ALTES EINGABEFORMAT	NEUES EINGABEFORMAT
Hinzufügen (Radio-Feld)	/api/v3/additional_fields	/api/v3/item_details
HINZUFÜGEN (Boolesches Feld)	/api/v3/additional_fields	/api/v3/item_details
HINZUFÜGEN (Numerisches Feld)	/api/v3/additional_fields	/api/v3/item_details
HINZUFÜGEN (Einzeiliges Feld)	/api/v3/additional_fields	/api/v3/item_details
Aktualisieren (Einzeiliges Feld)	/api/v3/additional_fields	/api/v3/item_details
Aktualisieren (Boolesches Feld)	/api/v3/additional_fields	/api/v3/item_details
Aktualisieren (Radio-Feld)	/api/v3/additional_fields	/api/v3/item_details
Aktualisieren (Numerisches Feld)	/api/v3/additional_fields	api/v3/item_details
Abrufen (Einzeiliges Feld)	/api/v3/additional_fields	/api/v3/item_details
Abrufen (Radio-Feld)	/api/v3/additional_fields	/api/v3/item_details
Abrufen (Boolesches Feld)	/api/v3/additional_fields	/api/v3/item_details
Abrufen (Numerisches Feld)	/api/v3/additional_fields	/api/v3/item_details
Alle abrufen	/api/v3/additional_fields	api/v3/item_details
Einzeln löschen	/api/v3/additional_fields	/api/v3/item_details
Massenhaft löschen	/api/v3/additional_fields	/api/v3/item_details
Zugehörige Checklisten für ein zusätzliches Checklistenfeld abrufen	/api/v3/checklist_items	api/v3/checklist_item_templates
Checkliste hinzufügen	/api/v3/checklists	/api/v3/checklist_templates
Checkliste aktualisieren	/api/v3/checklists	/api/v3/checklist_templates
Checkliste abrufen	/api/v3/checklists	/api/v3/checklist_templates
ALLE CHECKLISTEN ABRUFEN	/api/v3/checklists	/api/v3/checklist_templates
Checkliste löschen	/api/v3/checklists	/api/v3/checklist_templates
Checklisten massenhaft löschen	/api/v3/checklists?<ids>	/api/v3/checklist_templates?<ids>
Checklistenverlauf abrufen	/api/v3/checklists/<id>/history	/api/v3/checklist_templates/<id>/history
Zugehörige Anfragevorlagen einer Checkliste abrufen	/api/v3/template_checklists	/api/v3/template_checklists
Checklisten einer Anfragevorlage zuordnen	/api/v3/request_templates/<id>/checklists	api/v3/request_templates/<id>/checklists
Zuordnung von Checklisten von Anfragevorlage aufheben	api/v3/request_templates/<id>/checklists?<ids>	/api/v3/request_templates/<id>/checklists?<ids>
Zugehörige Checklisten der Anfragevorlage abrufen	/api/v3/request_templates/<id>/checklists	/api/v3/request_templates/<id>/checklists
Checklisten der Anfragevorlage neu anordnen	/api/v3/request_templates/<id>/checklists	/api/v3/request_templates/<id>/checklists
Anfrage mit Checklisten erstellen	/api/v3/requests	/api/v3/requests
Checklisten einer Anfrage zuordnen	/api/v3/requests/<id>/associate_checklists	/api/v3/requests/<id>/checklists
Checklisten einer Anfrage abrufen	/api/v3/requests/<id>/checklists	/api/v3/requests/<id>/checklists
Radio-Checklistenpunkt aktualisieren	/api/v3/requests/<id>/checklists/<id>/checklist_items	/api/v3/requests/<id>/checklists/<id>/checklist_items
Booleschen Checklistenpunkt aktualisieren	/api/v3/requests/<id>/checklists/<id>/checklist_items	/api/v3/requests/<id>/checklists/<id>/checklist_items
Numerischen Checklistenpunkt aktualisieren	/api/v3/requests/<id>/checklists/<id>/checklist_items	/api/v3/requests/<id>/checklists/<id>/checklist_items
Einzeiligen Checklistenpunkt aktualisieren	/api/v3/requests/<id>/checklists/<id>/checklist_items	/api/v3/requests/<id>/checklists/<id>/checklist_items
Checklistenpunkt löschen	/api/v3/requests/<id>/checklists/<id>/checklist_items/<id>	/api/v3/requests/<id>/checklists/<id>/checklist_items/<id>
Checklistenpunkte massenhaft löschen	/api/v3/requests/<id>/checklists/<id>/checklist_items?i<ids>	/api/v3/requests/<id>/checklists/<id>/checklist_items?<ids>
Aktualisierung des Checklistenstatus	/api/v3/requests/<id>/checklists/<id>	/api/v3/requests/<id>/checklists/<id>
Checkliste löschen	/api/v3/requests/<id>/checklists/<id>	/api/v3/requests/<id>/checklists/<id>
Checklisten massenhaft löschen	/api/v3/requests/<id>/checklists?<ids>	/api/v3/requests/<id>/checklists?<ids>