Benutzer verwalten
In manchen Fällen kann es sein, dass Sie Benutzern einen direkten oder Single-Sign-On-Zugriff zur Yext-Plattform geben möchten. Vielleicht möchten Sie z. B. einem Franchisenehmer direkten Zugang zu seinen Standortdaten geben. Es kann aber sein, dass Sie gleichzeitig auch die Art des Zugangs für bestimmte Nutzer selbst festlegen möchten. Vielleicht sollen sie nur auf Daten für den jeweiligen Standort zugreifen oder nur bestimmte Bereiche des Dashboards nutzen können. Glücklicherweise ist über die Kontoeinstellungs-API beides möglich.
BITTE BEACHTEN SIE: Um diese API nutzen zu können, müssen Sie gemeinsam mit Ihrem Yext-Kundenbetreuer benutzerdefinierte Benutzerrollen erstellen.

Aufrufen verfügbarer Rollen

Bevor wir mit der Kontoeinstellungs-API loslegen, lassen Sie uns kurz einen Blick darauf werfen, welche Rollen für Ihre App verfügbar sind. Das tun wir mit der Anfrage „Roles: Get“. Rollen legen fest, auf welche Funktionen ein Benutzer zugreifen und welche er nutzen kann. Sie können für einen Benutzer auf Konto-Ebene, Standort-Ebene oder Ordner-Ebene angewendet werden.
GEThttps://api.yext.com/v2/accounts/me/roles?v=YYYYMMDD&api_key=API_KEY

Wenn diese Anfrage erfolgreich war, werden die Anzahl sowie eine Liste aller Rollenobjekte angezeigt. Wenn Sie keine Rollen definiert haben, ist die Rollenliste leer. Bitte sprechen Sie mit Ihrem Kundenbetreuer, um herauszufinden, ob benutzerdefinierte Rollen zu Ihrem Konto hinzugefügt werden können. Wenn Sie über Rollen verfügen, erscheint im Antwortfeld in etwa Folgendes:
{
	"count": 1,
	"roles": [{
		"id": 20,
		"name": "Kundenbetreuer"
	}]
}

Einen Benutzer anlegen

Wir wissen nun, dass Rollen für Ihr Konto verfügbar sind. Lassen Sie uns jetzt einen neuen Benutzer erstellen. Hierfür brauchen wir die Anfrage „Users: Create“.
Hinweis: Beim Erstellen eines Benutzers müssen Sie die Felder firstName (Vorname), lastName (Nachname) und emailAddress (E-Mail-Adresse) angeben.
POSThttps://api.yext.com/v2/accounts/{accountId}/users?v=YYYYMMDD&api_key=API_KEY
 
{
	"id": "testUser",
	"firstName": "Max",
	"lastName": "Mustermann",
	"username": "MustermannSuperTest",
	"emailAddress": "john.doe@emails.com",
	"phoneNumber": "201-888-8888",
	"password": "aljnt23q;ob5t",
	"acl": [{
		"roleId": "20",
		"roleName": "Kundenbetreuer",
		"on": "Ihre Konto-ID",
		"accountId": "Ihre Konto-ID",
		"onType": "KONTO"
	}]
}
Wenn die Anfrage erfolgreich war, erhalten Sie eine 201-Antwort, in der die von Ihnen angegebene Benutzer-ID enthalten ist.

Benutzer abrufen

Lassen Sie uns den Benutzer bestätigen, den Sie mit der Anfrage „Users: Get“ angelegt haben.
GEThttps://api.yext.com/v2/accounts/[accountId]/users/[userId]?v=YYYYMMDD&api_key=API_KEY
Als Antwort erhalten Sie ein Benutzerobjekt mit den zuvor von Ihnen angegebenen Daten.
{
	"id": "testUser",
	"firstName": "Max",
	"lastName": "Mustermann",
	"username": "MustermannSuperTest",
	"emailAddress": "john.doe@emails.com",
	"phoneNumber": "201-888-8888",
	"password": "aljnt23q;ob5t",
	"acl": [{
		"roleId": "20",
		"roleName": "Kundenbetreuer",
		"on": "Ihre Konto-ID",
		"accountId": "[IHRE KONTO-ID]",
		"onType": "Konto"
	}],
	"sso": false
}

Benutzerdaten aktualisieren

Jetzt können wir den Benutzer, den Sie angelegt haben, bearbeiten. Mit der unten stehenden Anfrage aktualisieren wir die Telefonnummer eines Benutzers.Bitte beachten Sie, dass Sie beim Bearbeiten eines Benutzers die Felder id, firstName, lastName, username, emailAddress und phone angeben müssen.
PUThttps://api.yext.com/v2/accounts/{accountId}/users/{userId}?v=YYYYMMDD&api_key=API_KEY
 
{ 
	"id": "testUser",
	"firstName": "John",
	"lastName": "Doe",
	"username": "johnDoeSuperTest",
	"emailAddress": "john.doe@emails.com",
	"phoneNumber": "2013230000" 
}
Ähnlich wie bei der Anfrage „Users: Create“ erhalten Sie eine 200-Antwort mit der Benutzer-ID im Antworttext, etwa so:
{
        "id": "testUser"
}
Probieren Sie ein paar weitere Aktualisierungsanfragen aus, um festzustellen, welche Benutzerdaten Sie sonst noch ändern können.

Benutzerpasswörter aktualisieren

Beim Testen ist Ihnen vielleicht aufgefallen, dass über die Anfrage „User: Update“ das Benutzerpasswort nicht aktualisiert werden kann. Aus Sicherheitsgründen müssen Sie folgende Anfrage senden, um einem Benutzer ein neues Passwort zuzuweisen:
PUThttps://api.yext.com/v2/accounts/{accountId}/users/{userId}/password?v=YYYYMMDD&api_key=API_KEY
 
{
        "newPassword": "meinNeuesPasswort"
}
Auf diese Anfrage sollten Sie eine 200-Antwort ohne Antworttext erhalten. Versuchen Sie jetzt, ein sichereres, schwerer zu erratendes Passwort zu vergeben.

Einen Benutzer löschen

Es ist zwar toll, dass man Benutzer über die API hinzufügen und bearbeiten kann, doch es kann auch vorkommen, dass Sie einen Benutzer entfernen müssen. Wenn jemand zum Beispiel keine Verbindung mehr zu Ihrem Unternehmen hat, möchten Sie wahrscheinlich nicht, dass er die Standortdaten Ihres Unternehmens anzeigen oder bearbeiten kann. Sie können diesen Benutzerzugang mit der Anfrage „Users: Delete“ entfernen:
DELETEhttps://api.yext.com/v2/accounts/{accountId}/users/{userId}?v=YYYYMMDD&api_key=API_KEY
Auf diese Anfrage erhalten Sie eine 200-Antwort mit leerem Antworttext. Dies kann nicht rückgängig gemacht werden, überlegen Sie also bitte genau, bevor Sie Benutzer löschen!