KI-Suche Externe Anwenderzuordnungs-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 4 Minuten Lesedauer

    • Die API für die externe Benutzerzuordnung von AI Search bietet Endpunkte, die die Erfassung von Benutzerzuordnungsinformationen 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 Benutzerzuordnungen in eine KI-Suche Benutzerzuordnungstabelle. Jede Zuordnung gibt extern definierte Benutzer- und Gruppenaliase für einen Now Platform -Benutzer an. KI-Suche verwendet diese Aliasse, um zu bestimmen, welche externen Dokumentsuchergebnisse der Benutzer anzeigen kann.

    Informationen dazu, wie die externe Inhaltssicherheit von KI-Suche externe Benutzerzuordnungen verwendet, finden Sie unter Externe Inhaltssicherheit für die KI-Suche.

    Benutzer- und Gruppennamen in externen Benutzerzuordnungen müssen mit denen übereinstimmen, die in den Sicherheitszugriffsberechtigungen für externe Dokumente angegeben sind, die über den POST-Endpunkt /ais/external_content/ingestDocument/{schema_table_name}der API für externe Inhaltserfassung erfasst werden. Weitere Informationen zum Erfassen externer Dokumente mit Sicherheitszugriffsberechtigungen für extern definierte Benutzer und Gruppen finden Sie unter Externe Inhaltserfassungs-API.

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

    URL-Format

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

    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 Benutzerzuordnungstabelle KI-Suche, in der die importierten Zuordnungen angezeigt werden sollen. Beispiel: x_snc_sharepoint_user_table.
    Hinweis:
    Sie müssen die Zielbenutzerzuordnungstabelle KI-Suche über erstellen KI-Suche > Externer Inhalt > Anwenderzuordnung erstellen -Modul, bevor dieser Endpunkt verwendet wird. Wenn Sie eine Benutzerzuordnungstabelle angeben, die nicht vorhanden ist, 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 Benutzerzuordnung darstellt, die in die angegebene Zieltabelle importiert werden soll.

    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 Benutzer Now Platform festgelegt werden soll, der durch den Parameter {object}.records.mapping_value angegeben wird.

    Datentyp: Array

    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 Benutzers ist, der als Alias für den Benutzer Now Platform festgelegt werden soll, der durch den Parameter {object}.records.mapping_value angegeben ist.

    Datentyp: Array

    Werte können in einem beliebigen Format vorliegen, abhängig von den Namen der extern definierten Benutzerkonten, die für die Benutzerzuordnung 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 in der Benutzertabelle [sys_user] eindeutig identifiziert. Alle extern definierten Benutzer- und Gruppenaliasnamen in der Anforderung werden dem Benutzer Now Platform mit dieser E-Mail-Adresse zugeordnet.
    Hinweis:
    Die API behandelt diesen Parameter als eindeutigen Bezeichner für den Benutzerzuordnungsdatensatz. Wenn Sie eine andere Benutzerzuordnung mit demselben „mapting_value“ wie ein vorhandener Benutzerzuordnungsdatensatz importieren, überschreibt der neue Datensatz den vorhandenen Datensatz.

    Datentyp: Zeichenfolge

    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-Antwortcodesder 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.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    Fehler

    Objekt, das den während der Verarbeitung der Anforderung aufgetretenen Fehler beschreibt.

    Datentyp: Objekt

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

    Details des Fehlers, der während der Verarbeitung der Anforderung aufgetreten ist.

    Datentyp: Zeichenfolge
    Fehler.Nachricht

    Meldung für den Fehler, der während der Verarbeitung der Anforderung aufgetreten ist.

    Datentyp: Zeichenfolge
    import_set_id

    Sys_id für den neuen Datensatz, der in der Tabelle „Import Set“ [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-Import Set“ [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 Anforderungsfehler beschreibt.

    Datentyp: Zeichenfolge
    status

    Status einer nicht erfolgreichen Anforderung.

    Gültige Werte:
    • failure

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Importieren Sie extern definierte Benutzer- und Gruppenaliase für die Now Platform -Benutzer Beth Anglin und Abel Tuter in eine KI-Suche -Benutzerzuordnungstabelle 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 Import Set- und Multi Import Set-Datensätze.

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

    cURL-Anforderung

    Ungültige Anforderung importieren, 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 Status 400 fehl, und die Antwort gibt die Art des Fehlers an.

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