Vollständige API-Referenz: developer.universally.com enthält die Live-Spezifikation für die Translator API und die Platform API mit jedem Feld, Statuscode und Antwortbeispiel. Diese Seite behandelt, was man darüber wissen sollte.
Jede Universally API-Anfrage wird mit einem API-Schlüssel authentifiziert, der im X-API-Key HTTP-Header übergeben wird.
X-API-Key: your_api_key_here
Zwei Arten von Schlüsseln
Sie sind nicht austauschbar, und die Übermittlung des falschen Schlüssels gibt API_KEY_INVALID zurück. Welchen Sie benötigen, hängt vom Dienst ab, den Sie aufrufen.
| Projektschlüssel | Plattform-API-Schlüssel | |
|---|---|---|
| Sieht aus wie | ein 64-stelliger String | beginnt mit pak_ |
| Gehört zu | ein Projekt | ein Arbeitsbereich |
| Erstellt in | den API-Einstellungen des Projekts | dem Tab API-Schlüssel des Arbeitsbereichs |
| Funktioniert auf | translator.universally.com und den Connect-Endpunkten auf api.universally.com |
der Plattform-API auf api.universally.com |
| Läuft ab | nein | ja, Sie wählen, wann |
| Geltungsbereich | alles, was der Projektschlüssel tun kann | nur die Berechtigungen, die bei der Erstellung angekreuzt wurden |
Das Übersetzen von Inhalten verwendet den Projektschlüssel. Das Verwalten von Projekten, Sprachen und gespeicherten Zeichenketten aus Ihren eigenen Tools verwendet einen Plattform-API-Schlüssel.
Einen Projektschlüssel erhalten
Ein Projektschlüssel wird automatisch generiert, wenn Sie ein Projekt erstellen. Öffnen Sie das Projekt und gehen Sie zu API-Einstellungen, um ihn anzuzeigen, zu kopieren oder neu zu generieren. Die Anzeige erfordert die Berechtigung für API-Schlüssel. Es gibt keinen Endpunkt zum Erstellen eines solchen Schlüssels.
Das sofortige Neuerstellen des Schlüssels macht den vorherigen ungültig. Jede Integration, die den alten Schlüssel verwendet, erhält API_KEY_INVALID, bis Sie ihn aktualisieren.
Einen Plattform-API-Schlüssel erhalten
Öffnen Sie den Arbeitsbereich und gehen Sie zu API-Schlüssel, dann erstellen Sie einen. Sehen Sie Finden Sie Ihren API-Schlüssel für die Felder, einschließlich des Ablaufdatums und der Berechtigungsliste, und beachten Sie, dass der Schlüssel nur einmal angezeigt und danach nicht mehr abgerufen werden kann.
So halten Sie Ihren Schlüssel sicher
Ihr Schlüssel kann die übersetzten Wörter Ihres Plans verbrauchen, behandeln Sie ihn also wie ein Passwort:
- Senden Sie Anfragen von einem Server, einer Edge-Funktion oder einem Backend-Job. Betten Sie den Schlüssel niemals in Browser-JavaScript, mobile App-Bundles oder Clients ein, die ein Benutzer einsehen kann.
- Halten Sie den Schlüssel aus der Versionskontrolle heraus. Laden Sie ihn aus einer Umgebungsvariable oder einem Secrets Manager.
- Wenn ein Client (ein Browser oder eine App) übersetzte Inhalte benötigt, leiten Sie die Anfrage über Ihr eigenes Backend, damit der Schlüssel serverseitig bleibt.
Da der Translator Cross-Origin-Anfragen zulässt, könnte ein kompromittierter Schlüssel von überall verwendet werden. Wenn Sie vermuten, dass Ihr Schlüssel offengelegt wurde, generieren Sie ihn im Dashboard neu.
Überprüfung eines Schlüssels
Um zu überprüfen, ob ein Schlüssel gültig ist und zu welcher Website er gehört, rufen Sie den Verifizierungs-Endpunkt des API-Dienstes auf:
curl https://api.universally.com/connect/keys/verify \
-H "X-API-Key: your_api_key_here"
{
"success": true,
"data": {
"valid": true,
"siteId": "site_123",
"domain": "example.com"
},
"message": "API key is valid.",
"code": "KEY_VALID"
}
Dies ist während der Einrichtung nützlich, um zu bestätigen, dass eine Integration mit der richtigen Website verbunden ist, bevor echte Inhalte gesendet werden.
Authentifizierungsfehler
| Code | HTTP | Bedeutung |
|---|---|---|
API_SCHLÜSSEL_FEHLT |
401 | Es wurde kein X-API-Key-Header gesendet. |
API_SCHLÜSSEL_UNGÜLTIGES_FORMAT |
401 | Der Schlüssel hat kein anerkanntes Format. |
API_SCHLÜSSEL_FEHLERHAFT |
401 | Der Schlüssel konnte nicht analysiert werden. |
API_SCHLÜSSEL_UNGÜLTIG |
401 | Der Schlüssel ist wohlgeformt, aber nicht erkannt, oft nach der Neuerstellung. |
Siehe Fehler und Limits für die vollständige Tabelle.