Scompler GraphQL API
      Zurück zur Startseite
      1. Scompler Knowledge Base
      2. Integrationen
      3. Scompler GraphQL API

      Die Scompler GraphQl API

      Die Scompler GraphQL-API bietet eine GraphQL-API-Schnittstelle zur Integration von Scompler in Ihre Arbeitsabläufe und ermöglicht eine nahtlose Verbindung mit anderen Tools in Ihrem Tech-Stack.

      Package_PRO

       

      GraphQL ist eine Datenabfragesprache, die auf einem Schema basiert, dessen Gültigkeit durch die Spezifikation definiert wird.

       

      Authentifizierung mit der Scompler GraphQL-API

      Die Authentifizierung bei der Scompler GraphQL-API kann mithilfe eines persönlichen Zugriffstokens erfolgen. Ein API-Zugriffstoken ist ein sicherer Schlüssel, der es autorisierten Benutzern ermöglicht, sich mit der Scompler-API zu verbinden und Aufgaben basierend auf den ihnen zugewiesenen Berechtigungen auszuführen. Um ein API-Zugriffstoken zu generieren, muss ein Benutzer Mitglied einer Benutzergruppe sein, für die die Scompler-API-Berechtigung aktiviert ist.

       

      Schritte zur Generierung eines Scompler-API-Zugriffstokens:

      1. Navigieren Sie zu Ihren Scompler-Projekteinstellungen.

      2. Gehen Sie zum Tab „Scompler-API”.

      3. Klicken Sie auf „Token generieren“.

      4. Speichern Sie das Token sicher, da es nicht erneut angezeigt wird.

      DE_01_Token-Generierung

       

      HINWEIS: Das Token ist nur während des Erstellungsprozesses sichtbar und kann aus Sicherheitsgründen später nicht kopiert werden.

      Das Token übernimmt die Berechtigungen des Benutzers, der es generiert. Um API-Systemvorgänge von regulären Benutzeraktivitäten zu trennen, empfehlen wir, einen dedizierten Systembenutzer für die Generierung und Verwendung von API-Token zu erstellen. Dadurch werden die Protokolle übersichtlicher und es gibt weniger Verwirrung darüber, wer bestimmte Aktionen ausgeführt hat.

      Die regelmäßige Token-Rotation ist Teil der Einhaltung der Sicherheitsstandards ISO 27001 und TISAX durch Scompler. Token sind 180 Tage lang gültig und müssen vor Ablauf erneuert werden.

      Kommunikation mit der Scompler GraphQL-API

      Die gesamte Kommunikation mit der Scompler GraphQL-API erfolgt über einen einzigen Root-Endpunkt. Für pro.scompler.com lautet dieser:

      https://public-api.pro.scompler.com/graphql

      Im Fall von GraphQL sollte unabhängig davon, ob Sie eine Abfrage oder eine Mutation durchführen, das HTTP-Verb „POST“ verwendet werden. Eine Ausnahme bildet die Introspektionsabfrage, die mit „GET“ aufgerufen werden kann.

      Nachfolgend finden Sie die Anatomie einer typischen Anfrage, die mit „curl“ gesendet wird:

      shell
      curl -X POST https://public-api.pro.scompler.com/graphql \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer TOKEN" \
      -d ‘{"query":"query { languages(first:10) { nodes { id name } } }"}’

       

      Nachfolgend finden Sie die Anatomie einer typischen Mutation, die mit „curl“ aufgerufen wird:

      shell
      curl -X POST https://public-api.pro.scompler.com/graphql \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer TOKEN" \
      -d ‘{"query":"mutation { createLanguage(input: { params: { name: \"Polish\", slug: \"pl-PL\" } }) { data { id }"}’

      Schema-Introspektion

      Mit Introspektion können Sie das Schema bitten, sich selbst zu beschreiben. Diese Funktion wird häufig von Tools wie GraphQL Code Generator verwendet, um typsicheren Client-Code zu generieren.

       

      * Senden Sie eine „Schema“-Abfrage, um Informationen über das Schema abzurufen

      graphql
           query {
                 __schema {
                      types {
                            name
                            kind
                            description
                            fields {
                                 name
                            }
                      }
                 }
           }

      * Senden Sie eine „type“-Abfrage, um Informationen über einen der Typen abzurufen

      graphql
           query {
                 __type(name: "AccountGroup") {
                     name
                     kind
                     description
                      fields {
                          name
                     }
                 }
           }

      * Sie können auch eine „GET“-Anfrage senden, um die vollständigen Schemainformationen abzurufen

      shell

      curl https://public-api.pro.scompler.com/graphql \

      -H „X-Operation-Name: IntrospectionQuery“ \

      -H „Authorization: Bearer TOKEN“

      Wenn Sie eine Antwort mit "message: Unauthorized" oder "401 Unauthorized" erhalten, stellen Sie sicher, dass Sie ein gültiges Token verwenden.

       

      Entdecken der Scompler GraphQL-API-Funktionen

      Sie können Abfragen zu Ihren realen Daten direkt im Browser mithilfe einer IDE ausführen, die Dokumentation, Syntaxhervorhebung und Fehlerüberprüfung umfasst. Diese IDE ist eine Instanz von GraphiQL. Für pro.scompler.com ist sie im Browser unter folgender Adresse verfügbar:

      https://public-api.pro.scompler.com
       

      Bevor Sie Anfragen von der IDE senden können, müssen Sie auf der Registerkarte „Headers“ einen Header mit Ihrem persönlichen Zugriffstoken angeben:

      Limitierungen

      Die Scompler GraphQL-API enthält Beschränkungen zum Schutz vor übermäßigen oder missbräuchlichen Aufrufen. Diese Beschränkungen gelten sowohl auf Netzwerkebene (Ratenbeschränkungen) als auch auf Schemaebene (Knotenlimits).

      Um eine Überschreitung der Knotenlimits zu vermeiden, testen Sie Ihre Abfragen, bevor Sie sie in einer echten Anwendung verwenden.

      Um eine Überschreitung der Ratenbegrenzung zu vermeiden, sollten Sie zwischen den Änderungsanfragen mindestens 1 Sekunde warten und gleichzeitige Anfragen vermeiden.
       

      Knotenlimits

      1. Jede Anfrage wird anhand von Parametern wie der Anzahl und Art der Felder sowie der Verschachtelungstiefe ausgewertet. Wenn die berechneten Kosten den zulässigen Grenzwert überschreiten, wird die Anfrage nicht ausgeführt und ein Fehler zurückgegeben:
       

      json
          {
            "errors": [
              {
                "message": "Syntax Error: Query Cost limit of 1000 exceeded, found 1055.5."
              }
            ]
          }

       

      Das aktuelle Kostenlimit ist auf 1000 festgelegt.

      2. Jede paginierte Abfrage wird anhand der Anzahl der über die Argumente „first“ oder „last“ angeforderten Elemente weiter ausgewertet. Zusätzlich werden die Werte dieser Argumente selbst bewertet:

      • Eines dieser Argumente muss angegeben werden.
      • Der angegebene Wert muss im Bereich von 1 bis 100 liegen.

      Einzelne Aufrufe können insgesamt nicht mehr als 50.000 Knoten anfordern.
       

      Wenn die berechneten Kosten den zulässigen Grenzwert überschreiten, wird die Anfrage nicht ausgeführt und ein Fehler zurückgegeben:
       

      json
          {
            "data": null,
            "errors": [
              {
                "message": "Cannot request more than 1000 nodes in a single document. Please split your operation into multiple sub operations or reduce the amount of requested nodes.",
                "locations": [
                  {
                    "line": 1,
                    "column": 1
                  }
                ]
              }
            ]
          }

      3. Die maximale Verschachtelungstiefe innerhalb einer einzelnen Abfrage ist begrenzt. Wenn diese Grenze überschritten wird, wird die Abfrage nicht ausgeführt und ein Fehler zurückgegeben:

      json
          {
            "errors": [
              {
                "message": "Syntax Error: Query depth limit of 7 exceeded, found 12."
              }
            ]
          }

      Die maximale Verschachtelungstiefe ist auf 7 festgelegt.

       

      4. Es gibt eine Begrenzung für die maximale Anzahl von Aliasen in einer einzelnen Abfrage. Ein Beispiel für eine Abfrage mit Aliasen:

      graphql
          query {
            a: language(id: 10000654) {
              name
            }
            b: language(id: 10000655) {
              name
            }
          }  

       

      Wenn diese Grenze überschritten wird, wird die Abfrage nicht ausgeführt und ein Fehler zurückgegeben:

      json
          {
            "errors": [
              {
                "message": "Syntax Error: Aliases limit of 7 exceeded, found 10."
              }
            ]
          }

      Die maximale Anzahl von Aliasen ist auf 7 festgelegt.

       

      5. Die maximale Anzahl von Anweisungen in einer einzelnen Abfrage ist begrenzt. Ein Beispiel für eine Abfrage mit Anweisungen:

      graphql
          query ($name:Boolean!) {
            languages(first:10) {
              nodes {
                id
                name1: name @skip(if: $name)
                name2: name @skip(if: $name)
              }
            }
          } 

       

      Wenn diese Grenze überschritten wird, wird die Abfrage nicht ausgeführt und ein Fehler zurückgegeben:


      json
          {
            "errors": [
              {
                "message": "Syntax Error: Directives limit of 20 exceeded, found 22."
              }
            ]
          } 

      Die maximale Anzahl von Anweisungen beträgt 20.

       

      6. Die maximale Anzahl von Token in einer einzelnen Abfrage ist begrenzt. Einzelne Token werden als separate syntaktische Einheiten innerhalb der Abfrage betrachtet. Wenn eine Abfrage die zulässige Anzahl von Token überschreitet, wird sie nicht ausgeführt und ein Fehler wird zurückgegeben:
       

      json
          {
            "errors": [
              {
                "message": "Syntax Error: Token limit of 1000 exceeded."
              }
            ]
          } 

      Die maximale Anzahl von Token ist auf 1000 festgelegt.

       

      Ratenbegrenzung
       

      Für jeden Benutzer (jedes eindeutige persönliche Zugriffstoken) gilt eine Begrenzung der Anzahl gleichzeitig ausgeführter Abfragen und Mutationen innerhalb eines bestimmten Zeitintervalls.

      Wenn ein Benutzer mit einem bestimmten Token die festgelegten Grenzwerte überschreitet, kann er erst nach Ablauf des Intervalls neue Abfragen durchführen.

      Wenn das Limit überschritten wird, wird ein Fehler zurückgegeben:

      json
      {
        "errors": [
          {
            "message": "Rate limit of \"Query.*\" exceeded for \"Bearer TOKEN\"",
            "locations": [
              {
                "line": 2,
                "column": 3
              }
            ],
            "path": [
              "languages"
            ]
          }
        ],
        "data": {
          "languages": null
        }
      }

      Zusätzlich enthalten die Antwort-Header einen „Retry-After“-Header, der das Zeitintervall angibt, nach dem es sinnvoll ist, die Anfrage erneut zu versuchen. Sie sollten Ihre Anfragen erst nach Ablauf dieses Intervalls erneut versuchen:
       

      Retry-After: 300000ms

      Derzeit ist das Limit auf 500 Abfragen und 150 Mutationen innerhalb eines Zeitintervalls von 5 Minuten festgelegt.
       

      Fehler
       

      Wenn Fehler auftreten, bleibt der Antwortcode in den meisten Fällen „200“. Bei Fehlern während der Ausführung der Anfrage enthält die Antwort ein zusätzliches Feld „Fehler“ mit einer Beschreibung des Problems:
       

      graphql
      query {
        languages {
          nodes {
            id
            name
          }
        }
      }

      json
      {
        "data": null,
        "errors": [
          {
            "message": "Missing pagination argument for field 'languages'. Please provide either the 'first' or 'last' field argument.",
            "locations": [
              {
                "line": 2,
                "column": 3
              }
            ]
          }
        ]
      }

      Das gleiche Fehlerformat wird auch für Mutationen verwendet:
       

      graphql
      mutation {
        createLanguage(input: { params: { name: "Polish" } }) {
          data {
            id
          }
        }
      }

       

      json
      {
        "errors": [
          {
            "message": "Field \"LanguageCreateInput.slug\" of required type \"String!\" was not provided.",
            "locations": [
              {
                "line": 2,
                "column": 34
              }
            ]
          }
        ]
      }

      Seitennavigation

      Die Scompler GraphQL API hat eine Begrenzung der Anzahl von Elementen, die in einer einzigen Abfrage angefordert werden können. Bei der Verwendung solcher Abfragen müssen Sie entweder das „first“ oder das „last“ Argument angeben. Die Werte für diese Argumente müssen im Bereich von „1“ bis „100“ liegen.

      Wenn die von Ihnen angeforderten Informationen mehr Elemente enthalten als durch das „first“- oder „last“-Argument angegeben, wird die Abfrage in Seiten einer definierten Größe aufgeteilt.

      Die Seitennavigation erfolgt mithilfe eines Cursors und der „after“- oder „before“-Argumente. Sie können Cursorinformationen abrufen, indem Sie „pageInfo“ in einer paginierten Abfrage abfragen. Beispiel:


      graphql
      query {
        languages(first:50, after:null) {
          nodes {
            id
            name
          }
          pageInfo {
            startCursor
            endCursor
            hasNextPage
            hasPreviousPage
          }
        }
      }
       

      Um die nächste Seite mit Daten anzufordern, übergeben Sie den Wert von „pageInfo.endCursor“ an das Argument „after“. Zum Beispiel:


      graphql
      query {
        languages(first:50, after:"MQ") {
          nodes {
            id
            name
          }
          pageInfo {
            startCursor
            endCursor
            hasNextPage
            hasPreviousPage
          }
        }
      }
       

      Sie können „pageInfo.endCursor“ so lange verwenden, bis „pageInfo.hasNextPage“ gleich „false“ ist.

      Ebenso erfolgt die Rückwärtsnavigation mithilfe der Argumente „last“ und „before“ sowie der Werte „pageInfo.startCursor“ und „pageInfo.hasPreviousPage“.