Verwendung von Multi-Field Directives
Eine Multi-Field Directive ist eine Directive, die auf mehrere Felder angewendet werden kann, anstatt nur auf eines. Wenn sie aktiviert ist, wird allen Directives ein Argument affectAdditionalFieldsUnderPos hinzugefügt, mit dem die relativen Positionen zusätzlicher Felder angegeben werden können, auf die die Directive angewendet werden soll.
In der folgenden query wird die Directive @strTranslate beispielsweise nur auf das Feld content angewendet:
{
posts {
excerpt
content @strTranslate
}
}Die Directive @strTranslate kann auch auf das Feld excerpt angewendet werden, indem das Directive-Argument affectAdditionalFieldsUnderPos mit dem Wert [1] hinzugefügt wird (da 1 die relative Position des Feldes excerpt von der Directive @strTranslate aus ist):
{
posts {
excerpt
content
@strTranslate(
affectAdditionalFieldsUnderPos: [1]
)
}
}Die Anzahl der hinzuzufügenden Felder ist nicht begrenzt. In dieser query wird auch dateStr übersetzt:
{
posts {
dateStr
excerpt
content
@strTranslate(
affectAdditionalFieldsUnderPos: [1, 2]
)
}
}Das Feld, auf das die Directive natürlicherweise angewendet wird (wie content in allen obigen queries), muss nicht im Argument angegeben werden.
In der obigen query sind die relativen Positionen von der Directive @strTranslate zu den vorherigen Feldern:
- Position
2:dateStr - Position
1:excerpt - Position
0:content<= ist implizit, wird immer angewendet
Anwendungsfälle
Es gibt zwei Hauptanwendungsfälle für diese Funktion:
- Performance
- Erweiterte Funktionalität
Performance
Bei Directives, die Aufrufe an externe APIs ausführen, gilt: Je weniger Anfragen sie ausführen, desto schneller werden sie aufgelöst.
Das ist der Fall bei der Directive @strTranslate, die sich mit der Google Translate API verbindet. Normalerweise würde die query zum Übersetzen der Felder content und excerpt aus einer Liste von Posts so aussehen:
query {
posts {
excerpt @strTranslate
content @strTranslate
}
}Durch das zweimalige Hinzufügen von @strTranslate führt diese query zwei Anfragen an die Google Translate API aus (eine zum Übersetzen aller Werte von excerpt, eine für alle Werte von content).
Dank der Multi-Field Directives-Funktion übersetzt die folgende query ebenfalls alle Werte für beide Felder content und excerpt, führt aber stattdessen nur eine einzige Anfrage an die Google Translate API aus:
query {
posts {
excerpt
content
@strTranslate(
affectAdditionalFieldsUnderPos: [1]
)
}
}Erweiterte Funktionalität
Directives, die zusätzliche Felder erhalten, können ergänzende Berechnungen durchführen.
Die Directive @export exportiert beispielsweise normalerweise den Wert eines einzelnen Feldes, wie den Namen des eingeloggten Benutzers:
query GetLoggedInUserName {
me {
name @export(as: "userName")
}
}Über das Argument affectAdditionalFieldsUnderPos kann @export mehrere Felder empfangen und exportiert dann ein Dictionary, das diese Felder als Einträge enthält:
query GetLoggedInUserNameAndSurname {
me {
name
surname
@export(
as: "userProps"
affectAdditionalFieldsUnderPos: [1]
)
}
}@export erzeugt nun den folgenden Wert in der Variable $userProps
{
"name": "Leo",
"surname": "Loso"
}Konfiguration
Um Multi-Field Directives im GraphQL-Schema zu aktivieren oder zu deaktivieren, gehe zum Modul "Multi-Field Directives" auf der Einstellungsseite und aktiviere/deaktiviere das Kontrollkästchen Enable multi-field directives?:
Um Multi-Field Directives für einen bestimmten Endpoint zu aktivieren oder zu deaktivieren, wähle die gewünschte Option im Block "Multi-Field Directives" der entsprechenden Schema Configuration:
