SAM-Software-Nutzungsdaten-Integrations-API

Die SAM-Software Usage Data Integration- API bietet Endpunkte zum Erstellen und Aktualisieren von Datensätzen in der Tabelle „Softwarenutzung“ [samp_sw_usage].

Diese API erfordert die Aktivierung des Plugins „Software Asset Management Professional“ (com.snc.samp). Außerdem ist es erforderlich, dass Sie über die Rolle „sam_admin“ oder „sam_developer“ verfügen, um auf den Endpunkt zugreifen zu können.

SAM-Software Usage Data Integration – POST /sam_software_usage_integration/createOrUpdate

Erstellt oder aktualisiert einen angegebenen Datensatz in der Tabelle „Softwarenutzung“ [samp_sw_usage].

Sie können einen oder mehrere Softwarenutzungsdatensätze in einem einzigen Aufruf erstellen/aktualisieren.

URL-Format

Versionierte URL: /api/now/{api_version}/sam_software_usage_integration/createOrUpdate

Standard-URL: /api/now/sam_software_usage_integration/createOrUpdate

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

Tabelle : 2. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 3. Anforderungstextparameter (XML oder JSON)

Name

Beschreibung

items

Liste der Spaltennamen und Werte für jedes Feld, die im Softwarenutzungsdatensatz gespeichert werden sollen. Die Spalteninformationen, die Sie übergeben müssen, hängen von dem Wert ab, den Sie für reclamation_type angeben (ein Pflichtfeld): Mögliche reclamation_type Werte und die Spalteninformationen, die übergeben werden müssen: Gesamtnutzung: configuration_item last_used_time month_used norm_product Jahr letztes_verwendet_datum: configuration_item norm_product Die Kombination dieser Felder identifiziert einen Datensatz eindeutig. Wenn der Datensatz nicht in der Tabelle gefunden wird, wird ein neuer Datensatz mit den angegebenen Feldern erstellt. Andernfalls wird der vorhandene Datensatz aktualisiert. Datentyp: Array

Header

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
Content-Type	Datenformat des Anforderungstexts. 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-Antwortcodesder REST-API.

Tabelle : 6. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
401	Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
404	Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
405	Ungültige Methode. Die Funktion ist deaktiviert.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Antworttextparameter (JSON oder XML)

Name	Beschreibung
items	Name-Wert-Paar-Liste aller Felder im Softwarenutzungsdatensatz. Datentyp: Array (Inhalt variiert)

cURL-Anforderung

Das folgende Beispiel zeigt, wie ein neuer Softwarenutzungsdatensatz erstellt wird.

curl -X POST "https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{'items': [\
  {
    'configuration_item':'eaa9604d3790200044e0bfc8bcbe5dc1',\
    'month_used':2,\
    'norm_product':'40209c060b3022002d6c650d37673a89',\
    'norm_publisher':'24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type':'total_usage',\
    'usage_count': 13,\
    'total_usage_time':13,\
    'year':2020
  }\
]}"

{
  "result": {
    "reply": {
      "items": [
        {
          "configuration_item": "eaa9604d3790200044e0bfc8bcbe5dc1",
          "month_used": 2,
          "norm_product": "40209c060b3022002d6c650d37673a89",
          "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
          "reclamation_type": "total_usage",
          "usage_count": 13,
          "total_usage_time": 13,
          "year": 2020,
          "sysId": "13d15fe59d511010f8772c637e39afe5",
          "status": "INSERT"
        }
      ]
    },
    "message": "Ok"
  }
}

Das folgende Beispiel zeigt, wie mehrere Softwarenutzungsdatensätze in einem einzigen Aufruf aktualisiert werden.

curl -X POST "https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{'items': [\
  {\
    'configuration_item': 'eaa9604d3790200044e0bfc8bcbe5dc1',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 13,\
    'total_usage_time': 13,\
    'year': 2020
  },
  {\
    'configuration_item': '0aa9e80d3790200044e0bfc8bcbe5da0',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 19,\
    'total_usage_time': 19,\
    'year': 2020
  },
  {\
    'configuration_item': 'a0a9a80d3790200044e0bfc8bcbe5d3c',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 7,\
    'total_usage_time': 7,\
    'year': 2020},
  {\
    'configuration_item': '48a9280d3790200044e0bfc8bcbe5d55',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 1,\
    'total_usage_time': 1,\
    'year': 2020},
  {\
    'configuration_item': '61a9680d3790200044e0bfc8bcbe5d11',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 18,\
    'total_usage_time': 18,\
    'year': 2020}
]}"

{
  "result": {
    "reply": {
      "items": [
        {
          "configuration_item": "eaa9604d3790200044e0bfc8bcbe5dc1",
          "month_used": 2,
          "norm_product": "40209c060b3022002d6c650d37673a89",
          "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
          "reclamation_type": "total_usage",
          "usage_count": 13,
          "total_usage_time": 13,
          "year": 2020,
          "sysId": "13d15fe59d511010f8772c637e39afe5",
          "status": "INSERT"
        },
        {
          "configuration_item": "0aa9e80d3790200044e0bfc8bcbe5da0",
          "month_used": 2,
          "norm_product": "40209c060b3022002d6c650d37673a89",
          "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
          "reclamation_type": "total_usage",
          "usage_count": 19,
          "total_usage_time": 19,
          "year": 2020,
          "sysId": "2cd15fe59d521010f9772c637e39aff4",
          "status": "UPDATE"
        },
        {
          ...
        },
      ]
    },
    "message": "Ok"
  }
}