KI-Suche Zuordnungs-API für externe Anwender

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 4 Minuten Lesedauer

    • Die API für die externe Anwenderzuordnung der KI-Suche bietet Endpunkte, die die Erfassung von Anwenderzuordnungsinformationen aus externen Quellen im Index der Anwendung ServiceNow® KI-Suche ermöglichen.

    KI-Suche Externe Anwenderzuordnung – POST /ais/external_content/user_mapping/import_multiple/{target_table}

    Importiert eine Liste externer Anwenderzuordnungen in eine Anwenderzuordnungstabelle KI-Suche. Jede Zuordnung gibt extern definierte Benutzer- und Gruppenaliasse für einen Benutzer Now Platform an. KI-Suche verwendet diese Aliasse, um zu bestimmen, welche externen Dokumentsuchergebnisse der Benutzer anzeigen kann.

    Informationen dazu, wie die Sicherheit externer Inhalte KI-Suche externe Benutzerzuordnungen verwendet, finden Sie unter Sicherheit externer Inhalte für die KI-Suche.

    Anwender- und Gruppennamen in externen Anwenderzuordnungen müssen mit den Namen übereinstimmen, die in den Sicherheitszugriffsberechtigungen für externe Dokumente angegeben sind, die über den Endpunkt POST /ais/external_content/ingestDocument/{schema_table_name} der API zur Erfassung externer Inhalte erfasst wurden. Weitere Informationen zum Erfassen externer Dokumente mit Sicherheitszugriffsberechtigungen für extern definierte Benutzer und Gruppen finden Sie unter API zur Erfassung externer Inhalte.

    Um Importverläufe für externe Anwenderzuordnungsdatensätze anzuzeigen, die über diesen Endpunkt importiert wurden, navigieren Sie zu KI-Suche > Externer Content > Importverlauf von Anwenderzuordnungen. Von einem Verlaufsdatensatz aus können Sie die Datensätze „Importsatz“ [sys_import_set] und „Multi-Importsatz“ [sys_multi_import_set] für eine Importaufgabe anzeigen. Verwenden Sie Informationen aus diesen Datensätzen, um sicherzustellen, dass Ihre externen Anwenderzuordnungen ordnungsgemäß importiert wurden.

    URL-Format

    URL mit Versionsangabe: /api/now/{api_version}/ais/external_content/user_mapping/import_multiple/{target_table}

    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
    target_table
    Der Name der Anwenderzuordnungstabelle KI-Suche, in der die importierten Zuordnungen angezeigt werden sollen. Beispiel: x_snc_sharepoint_user_table.
    Hinweis:
    Sie müssen die Zuordnungstabelle für Zielbenutzer KI-Suche über erstellen KI-Suche > Externer Content > Anwenderzuordnung erstellen Modul, bevor Sie diesen Endpunkt verwenden. Wenn Sie eine nicht vorhandene Anwenderzuordnungstabelle angeben, schlägt die Anforderung fehl.

    Datentyp: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    {Objekt}

    Erforderlich. Unbenanntes Objekt.

    Datentyp: Objekt

    {
  "records": [Array]
}
    {object}.records

    Erforderlich. Array von Objekten, in dem jedes Objekt eine Anwenderzuordnung für den Import in die angegebene Zieltabelle darstellt.

    Datentyp: Array

    "records": [
  {
    "external_group": [Array],
    "external_user": [Array],
    "mapping_value": "String"
  }
]
    {object}.records.external_group

    Array von Zeichenfolgen, wobei jede Zeichenfolge der Name einer extern definierten Gruppe ist, die als Alias für den Anwender Now Platform festgelegt werden soll, der durch den Parameter „{object}.records.mapping_value“ angegeben wird.

    Datentyp: Array

    Die Werte können in einem beliebigen Format vorliegen, abhängig von den Namen der extern definierten Gruppen, die für die Benutzerzuordnung ausgewählt wurden. Beispiele:

    "external_group": [
  "itil",
  "hr-admin",
  "report-dev"
]
    {object}.records.external_user

    Array von Zeichenfolgen, wobei jede Zeichenfolge der Name eines extern definierten Anwenders ist, der als Alias für den Anwender Now Platform festgelegt werden soll, der durch den Parameter „{object}.records.mapping_value“ angegeben wird.

    Datentyp: Array

    Die Werte können in einem beliebigen Format vorliegen, abhängig von den Namen der extern definierten Anwenderaccounts, die für die Anwenderzuordnung ausgewählt wurden. Beispiele:

    "external_user": [
  "beth-anglin",
  "ad\beth.anglin",
  "beth-anglin@sharepoint"
]
    {object}.records.mapping_value
    E-Mail -Feldwert, der einen vorhandenen Datensatz eindeutig identifiziert. Alle extern definierten Aliasse für Anwender und Gruppen in der Anforderung werden dem Anwender Now Platform mit dieser E-Mail-Adresse zugeordnet.
    Hinweis:
    Die API behandelt diesen Parameter als eindeutigen Bezeichner für den Anwenderzuordnungsdatensatz. Wenn Sie eine andere Anwenderzuordnung mit dem gleichen Zuordnungswert (map_value) eines vorhandenen Anwenderzuordnungsdatensatzes importieren, überschreibt der neue Datensatz den vorhandenen Datensatz.

    Datentyp: Zeichenfolge

    Tabelle: Benutzer [sys_user]

    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ützt nur application/json.
    Content-Type Datenformat des Anforderungstexts. Unterstützt nur 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
    201 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Parameter des Antworttexts (JSON oder XML)

    Name Beschreibung
    Fehler

    Objekt, das den Fehler beschreibt, der bei der Verarbeitung der Anforderung aufgetreten ist.

    Datentyp: Objekt

    "error": {
  "detail": "String",
  "message": "String"
}
    Fehler.detail

    Details des Fehlers, der bei der Verarbeitung der Anforderung aufgetreten ist.

    Datentyp: Zeichenfolge
    Fehlernachricht

    Meldung für den Fehler, der bei der Verarbeitung der Anforderung aufgetreten ist.

    Datentyp: Zeichenfolge
    import_set_id

    Sys_id für den neuen Datensatz, der in der Importsatz-Tabelle [sys_import_set] durch eine erfolgreiche Anforderung erstellt wurde.

    Datentyp: Zeichenfolge
    multi_import_set_id

    Sys_id für den neuen Datensatz, der in der Tabelle „Multi-Importsatz“ [sys_multi_import_set] durch eine erfolgreiche Anforderung erstellt wurde.

    Datentyp: Zeichenfolge
    Ergebnis

    Ergebnis für eine nicht erfolgreiche Anforderung. Enthält eine Nachricht, die den Grund für den Fehler bei der Anforderung beschreibt.

    Datentyp: Zeichenfolge
    status

    Status einer nicht erfolgreichen Anforderung.

    Gültige Werte:
    • failure

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Importieren Sie extern definierte Anwender- und Gruppenaliasse für die Now Platform -Anwender Beth Anglin und Abel Tuter in eine KI-Suche -Anwenderzuordnungstabelle mit dem Namen x_snc_sharepoint_user_table.

    curl -X POST 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/x_snc_sharepoint_user_table' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password' \
  -d '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "itil",
          "itil-admin",
          "itil-dev"
        ]
      },
      {
        "mapping_value": "abel.tuter@example.com",
        "external_user": [
          "ad\abel-tuter",
          "abel.tuter@sharepoint"
        ],
        "external_group": [
          "hr",
          "hr-admin",
          "hr-dev"
        ]
      }
    ]
  }'

    Die Antwort zeigt die sys_ids für die generierten Datensätze für Importsätze und Multi-Importsätze.

    {
  "import_set_id": "6e9ddb629d987010f877878bd9f0e9dd",
  "multi_import_set_id": "269ddb629d987010f877878bd9f0e9de"
}

    cURL-Anforderung

    Importieren Sie eine ungültige Anforderung, die einen leeren Zuordnungsdatensatz enthält.

    curl 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/u_ext_content_user_mapping' \
  --request POST \
  --user 'username':'password' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "reports",
          "reports-admin",
          "reports-dev"
        ]
      },
      {}
    ]
  }'

    Die Anforderung schlägt mit dem Status 400 fehl, und in der Antwort wird die Art des Fehlers angegeben.

    {
  "result": "Error in processing the message"
}