Berechtigungs-API

Yokohama API-Referenz

Release

yokohama

ft:locale

de-DE

ft:publication_title

Yokohama API-Referenz

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

Berechtigungs-API

Freigeben Version: Yokohama

Aktualisiert 30. Januar 2025

11 Minuten Lesedauer

Die Entitlement API bietet Endpunkte zum Erstellen und Abrufen von Berechtigungsdatensätzen aus einer -Instanz.

Berechtigungsprüfungen finden im Rahmen von Post-Sales-Supportservices für Kunden statt, die ein Produkt erwerben, z. B. ein Gerät oder einen Computer. Berechtigungsprüfungen werden von Service Desk-Mitarbeitern durchgeführt, um zu bestimmen, welche Services Kunden für die von ihnen erworbenen Produkte erhalten können. Verwenden Sie die Berechtigungs -API, um Berechtigungen zu definieren und abzurufen.

Diese API greift auf Daten in den folgenden Tabellen zu und speichert sie:

Account [customer_account]
Verbraucher [csm_consumer]
Haushalt [csm_household]
Installationsbasis [sn_install_base_item]
Produktmodell [cmdb_model]
Produktangebot [sn_prd_pm_product_offering]
Verkauftes Produkt [sn_install_base_sold_product]

Für den Zugriff auf diese API müssen die folgenden Plugins in der zugehörigen Instanz aktiviert werden:

Kundenverträge und Berechtigungen (com.sn_pss_core)
Customer Service Install Base Management (com.snc.install_base)
Product Catalog Management Core (com.sn_prd_pm)

Um diese API erfolgreich aufzurufen, benötigen Sie außerdem die Rolle sn_pss_core.pss_integrator. Diese API wird im Namespace sn_pss_core ausgeführt.

Berechtigung – GET /sn_pss_core/entitlement/{id}

Gibt den angegebenen Berechtigungsdatensatz, die zugehörige Abdeckung und die Details zur aktuellen Nutzung zurück.

Es folgt die Liste der Tabellen, in denen die Berechtigungsdaten gespeichert werden:

Merkmale [sn_pss_core_entitlement_charakteristik]
Berechtigung [service_entitlement]
Berechtigungsnutzung [sn_pss_core_entitlement_usage]
Abgedeckte verkaufte Produkte [sn_install_base_m2m_contract_sold_product]: Diese Tabelle enthält Informationen zu abgedeckten verkauften Produkten und abgedeckten Installationsbasiselementen.

URL-Format

URL mit Versionsnummer: /api/sn_pss_core/{api_version}/entitlement/{id}

Standard-URL: /api/sn_pss_core/entitlement/{id}

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 1. Pfadparameter
Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel `v1` oder `v2`. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
id	Sys_id des abzurufenden Berechtigungsdatensatzes. Datentyp: Zeichenfolge Tabelle: Berechtigung [service_entitlement]

Tabelle : 2. Abfrageparameter
Name	Beschreibung
display_value	Typ der zurückzugebenden Daten. Gültige Werte: „falsch“: Gibt den `Wert` für alle Felder zurück. Beispiel: `„state":"draft“`. „wahr“: Gibt den `Anzeigewert` für alle Felder zurück. Beispiel: `„state":"Draft“` all: Gibt alle Informationen für alle Felder zurück. Datentyp: Zeichenfolge Standardwert: false

Tabelle : 3. Parameter des Anforderungstexts (JSON)
Name	Beschreibung
Keine

Kopfzeilen

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 4. Anforderungskopfzeilen
Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 5. Antwortkopfzeilen
Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 6. Statuscodes
Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
403	Unzulässig. Der Anwender hat keine Zugriffsrechte für den angegebenen Datensatz.
404	Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Parameter des Antwort-Haupttexts


Name	Beschreibung
Account	Sys_id des Account-Datensatzes, zu dem die Berechtigung gehört. Datentyp: Zeichenfolge Tabelle: Account [customer_account]
Verbraucher	Sys_id des Verbraucherdatensatzes, zu dem die Berechtigung gehört. Datentyp: Zeichenfolge Tabelle: Verbraucher [csm_consumer]
contract	Sys_id des Vertragsdatensatzes, zu dem die Berechtigung gehört. Datentyp: Zeichenfolge Tabelle: Servicevertrag [sn_pss_core_service_contract]
end_date	Enddatum der Berechtigung. Datentyp: Zeichenfolge Format: jjjj-mm-tt Standard: Endet nie, bis sie manuell entfernt werden.
Berechtigungsmerkmale	Liste der Merkmale, die der Berechtigung zugeordnet sind. Datentyp: Array von Objekten `"entitlement_characteristics" [ { "characteristic": "String", "characteristic_option": "String", "entitlement": "String", "entitlement_usage": [Array], "service_contract_line": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_updated_by": "String", "sys_updated_on": "String", "type": "String", "value": "String" } ]` Gespeichert in: Merkmal [sn_pss_core_entitlement_charakteristik]
Berechtigungsmerkmale.Merkmal	Sys_id des Merkmaldatensatzes, der der Berechtigung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Merkmal [sn_prd_pm_charakteristik]
Berechtigung_Merkmale.Merkmale_Option	Sys_id des Merkmalsoptionsdatensatzes, der der Berechtigung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Merkmalsoption [sn_prd_pm_characterist_option]
Berechtigung – Merkmale. Berechtigung	Sys_id des zugeordneten Berechtigungsdatensatzes. Datentyp: Zeichenfolge Tabelle: Berechtigung [service_entitlement]
Berechtigung_Merkmale.Berechtigung_Verwendung	Liste der Berechtigungsnutzungen, die dem Berechtigungsmerkmal zugeordnet sind. Datentyp: Array von Objekten `"entitlement_usage": [ { "entitlement": "String", "entitlement_characteristic": "String", "period_end": "String", "period_start": "String", "service_contract_line": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_updated_by": "String", "sys_updated_on": "String", "total_units": "String", "used_units": "String" } ]`
Entitlement_Merkmale.entitlement_usage.entitlement	Sys_id des Berechtigungsdatensatzes, der der Berechtigungsnutzung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Berechtigung [service_entitlement]
Berechtigung_Merkmale.Berechtigung_Verwendung.Berechtigung_Merkmale	Sys_id des Berechtigungsmerkmalsdatensatzes, der der Berechtigungsnutzung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Merkmal [sn_pss_core_entitlement_charakteristik]
Berechtigung_Merkmale.Berechtigung_Nutzung.Zeitraum_Ende	Enddatum, ab dem die Berechtigungsnutzung nicht mehr nachverfolgt wird. Datentyp: Zeichenfolge Format: jjjj-mm-tt
Berechtigung_Merkmale.Berechtigung_Nutzung.Zeitraum_Start	Startdatum, ab dem die Nutzung der Berechtigung nachverfolgt wird. Datentyp: Zeichenfolge Format: jjjj-mm-tt
Berechtigung_Merkmale.Berechtigung_Nutzung.Service_Vertragszeile	Sys_id der Servicevertragsposition, zu der die aktuelle Berechtigungsnutzung gehört. Datentyp: Zeichenfolge
Berechtigung_Merkmale.Berechtigung_Nutzung.sys_created_by	Name des Benutzers, der den Berechtigungsnutzungsdatensatz erstellt hat. Datentyp: Zeichenfolge
Berechtigung_Merkmale.Berechtigung_Verwendung.sys_created_on	Datum und Uhrzeit der Erstellung des Berechtigungsnutzungsdatensatzes. Datentyp: Zeichenfolge
Berechtigung_Merkmale.Berechtigung_Verwendung.Sys_ID	Sys_id des Berechtigungsnutzungsdatensatzes. Datentyp: Zeichenfolge Tabelle: Berechtigungsnutzung [sn_pss_core_entitlement_usage]
Berechtigung_Merkmale.Berechtigung_Nutzung.sys_updated_by	Name des Benutzers, der den Berechtigungsnutzungsdatensatz zuletzt aktualisiert hat. Datentyp: Zeichenfolge
Berechtigung_Merkmale.Berechtigung_Nutzung.sys_updated_on	Datum und Uhrzeit der letzten Aktualisierung des Berechtigungsnutzungsdatensatzes. Datentyp: Zeichenfolge
Berechtigung_Merkmale.Berechtigung_Nutzung.Gesamtanzahl_Einheiten	Gesamtabdeckungswert des zugeordneten Berechtigungsmerkmals. Datentyp: Zeichenfolge
Berechtigung_Merkmale.Berechtigung_Nutzung.Verwendete_Einheiten	Anzahl der vom Account oder Verbraucher verwendeten Einheiten zwischen period_start und period_end. Datentyp: Zeichenfolge
Berechtigungsmerkmale Typ	Typ des Berechtigungsmerkmals. Gültige Werte: Abdeckung „Abdeckung_und_Nutzung“ Datentyp: Zeichenfolge
Berechtigungsmerkmale.Wert	Wert des Merkmals. Datentyp: Zeichenfolge
Berechtigungsname	Name der Berechtigung. Datentyp: Zeichenfolge
Haushalt	Sys_id des Haushaltsdatensatzes, der der Berechtigung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Haushalt [csm_household]
install_base_items_covered	Liste der Installationsbasiselemente, die unter der Berechtigung abgedeckt sind. Datentyp: Array von Objekten `"install_base_items_covered": [ { "added": "String", "contract": "String", "entitlement": "String", "install_base": "String", "removed": "String", "service_contract_line": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_updated_by": "String", "sys_updated_on": "String" } ]` Tabelle: Abgedeckte verkaufte Produkte [sn_install_base_m2m_contract_sold_product]
install_base_items_covered.hinzugefügt	Datum, an dem das zugehörige Installationsbasiselement der Berechtigung hinzugefügt wurde. Datentyp: Zeichenfolge
install_base_items_covered.contract	Sys_id des Servicevertragsdatensatzes, der dem Installationsbasiselement zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Servicevertrag [sn_pss_core_service_contract]
install_base_items_covered.install_base	Sys_id des Installationsbasiselements, das von der Servicevertragsposition abgedeckt wird. Datentyp: Zeichenfolge Tabelle: Installationsbasiselement [sn_install_base_item]
install_base_items_covered.entfernt	Datum, an dem das zugehörige Installationsbasiselement aus der Berechtigung entfernt wurde. Datentyp: Zeichenfolge
Berechtigung „install_base_items_covered.“	Sys_id des Berechtigungsdatensatzes, der dem Installationsbasiselement zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Berechtigung [service_entitlement]
install_base_items_covered.service_contract_line	Sys_id des zugehörigen Datensatzes der Servicevertragsposition. Datentyp: Zeichenfolge Tabelle: Servicevertragsposition [sn_pss_core_service_contract_line]
install_base_items_covered.sys_created_by	Name des Benutzers, der den Datensatz des Installationsbasiselements erstellt hat. Datentyp: Zeichenfolge
install_base_items_covered.sys_created_on	Datum und Uhrzeit der Erstellung des Datensatzes des Installationsbasiselements. Datentyp: Zeichenfolge
install_base_items_covered.sys_id	Sys_id des abgedeckten Installationsbasiselements. Datentyp: Zeichenfolge Tabelle: Abgedeckte verkaufte Produkte [sn_install_base_m2m_contract_sold_product]
install_base_items_covered.sys_updated_by	Name des Benutzers, der den Datensatz des Installationsbasiselements zuletzt aktualisiert hat. Datentyp: Zeichenfolge
install_base_items_covered.sys_updated_on	Datum und Uhrzeit der letzten Aktualisierung des Datensatzes des Installationsbasiselements. Datentyp: Zeichenfolge
product	Sys_id des Produktmodelldatensatzes, der der Berechtigung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Produktmodell [cmdb_model]
product_offering	Sys_id des Produktangebotdatensatzes, der der Berechtigung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Produktangebot [sn_prd_pm_product_offering]
„sold_entitlement“	Sys_id des Datensatzes des verkauften Produkts, der der Berechtigung zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Verkauftes Produkt [sn_install_base_sold_product]
„sold_products_covered“	Liste der abgedeckten Produkte. Datentyp: Array von Objekten `"sold_products_covered": [ { "added": "String", "contract": "String", "entitlement": "String", "removed": "String", "service_contract_line": "String", "sold_product": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_updated_by": "String", "sys_updated_on": "String" } ]` Tabelle: Abgedeckte verkaufte Produkte [sn_install_base_m2m_contract_sold_product]
„sold_products_covered.added“.	Datum, an dem das zugehörige verkaufte Produkt der Berechtigung hinzugefügt wurde. Datentyp: Zeichenfolge Format: jjjj-mm-tt Standard: Aktuelles Datum
„sold_products_covered.contract“	Sys_id des Servicevertragsdatensatzes, der dem verkauften Produkt zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Servicevertrag [sn_pss_core_service_contract]
Berechtigung „sold_products_covered.entitlement“	Sys_id des Berechtigungsdatensatzes, der dem verkauften Produkt zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Berechtigung [service_entitlement]
„sold_products_covered.removed“	Datum, an dem das zugeordnete verkaufte Produkt aus der Berechtigung entfernt wurde. Datentyp: Zeichenfolge Format: jjjj-mm-tt Standard: Kein Enddatum
„sold_products_covered.service_contract_line“	Sys_id des Datensatzes der Servicevertragsposition, der dem verkauften Produkt zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Servicevertragsposition [sn_pss_core_service_contract_line]
„sold_products_covered“.sold_product	Sys_id des Produkts, das von der Berechtigung abgedeckt wird. Datentyp: Zeichenfolge Tabelle: Verkauftes Produkt [sn_install_base_sold_product]
„sold_products_covered.sys_created_by“	Name des Anwenders, der den Datensatz des abgedeckten verkauften Produkts erstellt hat. Datentyp: Zeichenfolge
„sold_products_covered.sys_created_on“	Datum und Uhrzeit der Erstellung des Datensatzes „Verkauftes Produkt abgedeckt“ Datentyp: Zeichenfolge
„sold_products_covered.sys_id“	Sys_id des von diesem Servicevertrag abgedeckten Produkts. Datentyp: Zeichenfolge Tabelle: Abgedeckte verkaufte Produkte [sn_install_base_m2m_contract_sold_product]
„sold_products_covered.sys_updated_by“	Name des Anwenders, der den Datensatz des verkauften Produkts zuletzt aktualisiert hat. Datentyp: Zeichenfolge
„sold_products_covered.sys_updated_on“	Datum und Uhrzeit der letzten Aktualisierung des Datensatzes des verkauften Produkts. Datentyp: Zeichenfolge
start_date	Startdatum der Berechtigung. Datentyp: Zeichenfolge Format: jjjj-mm-tt
state	Aktueller Status der Berechtigung. Gültige Werte: (Groß-/Kleinschreibung beachten) aktiv Abgebrochen Entwurf abgelaufen ausgesetzt Datentyp: Zeichenfolge
sys_created_by	Name des Benutzers, der den Berechtigungsdatensatz erstellt hat. Datentyp: Zeichenfolge
sys_created_on	Datum und Uhrzeit der Erstellung des Berechtigungsdatensatzes. Datentyp: Zeichenfolge
sys_id	Sys_id des zugeordneten Berechtigungsdatensatzes. Datentyp: Zeichenfolge Tabelle: Berechtigung [service_entitlement]
sys_updated_by	Name des Benutzers, der den Berechtigungsdatensatz zuletzt aktualisiert hat. Datentyp: Zeichenfolge
sys_updated_on	Datum und Uhrzeit der Erstellung des Berechtigungsdatensatzes. Datentyp: Zeichenfolge

cURL-Anforderung

Das folgende Beispiel zeigt, wie dieser Endpunkt aufgerufen wird, um eine Berechtigungsvorlage abzurufen.

curl "https://instance.servicenow.com/api/sn_pss_core/entitlement/fc73d2de89226110f877430a4e008" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Antwort:

{
  "result": {
    "sys_id": "5a651515d1f53110f8776589fa411f7b",
    "sys_created_by": "admin",
    "sys_updated_by": "admin",
    "sys_created_on": "2023-10-09 11:31:59",
    "sys_updated_on": "2023-10-09 11:31:59",
    "entitlement_name": "indep entl",
    "account": "4c325111d1f53110f8776589fa411f3d",
    "consumer": null,
    "household": null,
    "contract": null,
    "service_contract_line": null,
    "state": "active",
    "product_offering": null,
    "sold_entitlement": null,
    "product": null,
    "start_date": "2023-10-03",
    "end_date": "2024-12-03",
    "sold_products_covered": [
      {
        "sys_id": "d6651515d1f53110f8776589fa411f7c",
        "sys_created_by": "admin",
        "sys_updated_by": "admin",
        "sys_created_on": "2023-10-09 11:31:59",
        "sys_updated_on": "2023-10-09 11:31:59",
        "contract": null,
        "service_contract_line": null,
        "entitlement": "5a651515d1f53110f8776589fa411f7b",
        "sold_product": "0df21151d1f53110f8776589fa411f1b",
        "added": "",
        "removed": ""
      }
    ],
    "install_base_items_covered": [
      {
        "sys_id": "12651515d1f53110f8776589fa411f7d",
        "sys_created_by": "admin",
        "sys_updated_by": "admin",
        "sys_created_on": "2023-10-09 11:31:59",
        "sys_updated_on": "2023-10-09 11:31:59",
        "contract": null,
        "service_contract_line": null,
        "entitlement": "5a651515d1f53110f8776589fa411f7b",
        "install_base": "e2639951d1f53110f8776589fa411f2b",
        "added": "",
        "removed": ""
      }
    ],
    "entitlement_characteristics": [
      {
        "sys_id": "12651515d1f53110f8776589fa411f7e",
        "sys_created_by": "admin",
        "sys_updated_by": "admin",
        "sys_created_on": "2023-10-09 11:31:59",
        "sys_updated_on": "2023-10-09 11:31:59",
        "service_contract_line": null,
        "entitlement": "5a651515d1f53110f8776589fa411f7b",
        "characteristic_option": "495149b7539e61106bfcddeeff7b1262",
        "value": "5",
        "characteristic": "63418db7539e61106bfcddeeff7b1238",
        "type": "coverage_and_usage",
        "entitlement_usage": [
          {
            "sys_id": "de651515d1f53110f8776589fa411f7e",
            "sys_created_by": "admin",
            "sys_updated_by": "admin",
            "sys_created_on": "2023-10-09 11:31:59",
            "sys_updated_on": "2023-10-09 11:31:59",
            "entitlement": "5a651515d1f53110f8776589fa411f7b",
            "service_contract_line": null,
            "entitlement_characteristic": "12651515d1f53110f8776589fa411f7e",
            "period_start": "2023-10-03",
            "period_end": "2024-12-03",
            "total_units": "5",
            "used_units": "25"
          }
        ]
      }
    ]
  }
}

Berechtigung: POST /sn_pss_core/entitlement

Erstellt einen Berechtigungsdatensatz und alle zugehörigen Detaildatensätze.

Es folgt die Liste der Tabellen, in denen die Berechtigungsdaten gespeichert werden:

Merkmal [sn_pss_core_entitlement_charakteristik]
Berechtigung [service_entitlement]
Berechtigungsnutzung [sn_pss_core_entitlement_usage]
Abgedeckte verkaufte Produkte [sn_install_base_m2m_contract_sold_product]: Diese Tabelle enthält Informationen zu abgedeckten verkauften Produkten und abgedeckten Installationsbasiselementen.

URL-Format

URL mit Versionsnummer: /api/sn_pss_core/{api_version}/entitlement

Standard-URL: /api/sn_pss_core/entitlement