CCCIF-Medienressourcen-API

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

    • Die Medienressourcen-API des Custom Chat Chatbot Interoperability Framework (CCCIF) stellt Endpunkte bereit, die es einem primären Bot ermöglichen, Anhänge in die zugeordnete Instanz ServiceNow hochzuladen.

    Rufen Sie diese API in Ihrem primären Bot auf, um private Anhänge von einem Anwender hochzuladen, der eine Konversation über Virtual Agent (VA) führt. Anschließend müssen Sie den Parameter „mediaUrl“, der von dieser API zurückgegeben wird, an die VA-API senden.

    Wenn der Anhang öffentlich ist, können Sie die Anhangs-URL einfach im Anforderungstext Ihres Anrufs für die Virtual Agent-Bot-Integration senden.

    Für den Zugriff auf diese API muss das Plugin „Conversational Custom Chat Integration“ (com.glide.cs.custom.adapter) aktiviert sein. Außerdem müssen die Systemeigenschaften für Anhänge konfiguriert werden.

    Weitere Informationen zu den Fähigkeiten der Virtual Agent -API finden Sie unter Virtual Agent-API.

    CCCIF: POST /cccif/media/upload

    Lädt einen privaten Anhang in die aufgerufene Instanz ServiceNow hoch, die den Anhang in der Tabelle „Anhänge“ [sys_attachment] speichert.

    Rufen Sie diese Methode in Ihrem primären Bot auf, um private Anhänge von einem Anwender hochzuladen, der eine Konversation über Virtual Agent (VA) führt. Anschließend müssen Sie den Parameter mediaUrl, der von dieser Methode zurückgegeben wird, mit Virtual Agent-Bot Integration APIan die VA-API senden.

    URL-Format

    URL mit Versionsnummer: /api/now/{api_version}/cccif/media/upload

    Standard-URL: /api/now/cccif/media/upload

    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
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter
    Name Beschreibung
    file Erforderlich. Pfad der hochzuladenden Datei

    Datentyp: Zeichenfolge, z. B. @File path<file_path>
    provider_application_id Sys_id der „sys_cs_provider_application“, die mit dem VA-Bot interagiert.

    Standard: Sys_id der VA-Bot-zu-Bot-Anbieter-Anwendung
    user_id Erforderlich. Eindeutiger Anwender-ID des Anwenders, der mit dem VA-Bot interagiert. Dies kann eine beliebige Zeichenfolge sein, die für jeden Anwender eindeutig ist.

    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ützte Typen: multipart/form-data.
    Tabelle : 5. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Inhaltstyp Datenformat des Antworttexts. Unterstützt nur application/json.

    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.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    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 (JSON)

    Name Beschreibung
    attachmentId Sys_id des gespeicherten Anhangs.

    Datentyp: Zeichenfolge
    Fehler Beschreibung eines Fehlers, der bei der Verarbeitung der Anforderung erkannt wurde.

    Datentyp: Objekt

    "error": {
  "detail": "String",
  "message": "String"
}
    Fehler.detail Details zum aufgetretenen Fehler.

    Datentyp: Zeichenfolge
    Fehlernachricht Meldung, die den ausgelösten Fehler beschreibt.

    Datentyp: Zeichenfolge
    mediaUrl Anhangs-URL, die an den primären Bot gesendet wird, um auf den Anhang zuzugreifen. Der primäre Bot muss diese URL im Parameter message.attachment.url des Anforderungstexts des POST-Endpunkts „/sn_va_as_service/bot/integration“ senden.

    Datentyp: Zeichenfolge
    name Dateiname des Anhangs.

    Datentyp: Zeichenfolge
    state Status des Anhangs in der Anhangstabelle.
    Mögliche Werte:
    • Verfügbar
    • bedingt verfügbar
    • nicht verfügbar
    • Ausstehend

    Datentyp: Zeichenfolge

    cURL-Anforderung

    In diesem Beispiel wird gezeigt, wie Sie einen PNG-Dateianhang hochladen.

    curl --location --request POST 'https://instance.servicenow.com/api/now/v1/cccif/media/upload' \
--header 'Authorization: Basic xxxxxxxxxxxxx' \
--header 'Content-Type:multipart/form-data' \
--form 'user_id="lincoln"' \
--form 'file=@"/Users/Desktop/Screenshot 2021-10-25 at 5.08.14 PM.png"'

    Antwort:

    Response :{
  "result": {
    "mediaUrl": "https://instance.servicenow.com/api/now/v1/cs/media/vGfewkfAv0VBo2RxmlTM448L789Pp6rqLFLUNYQxZsUUFrsgMA8aW9W0zWx1a5fG",
    "name": "Screenshot 2021-10-25 at 5.08.14 PM.png",
    "state": "pending",
    "attachmentId": "299c648887b73c1022b6a6cd0ebb3534"
  }