Utilisation des directives pour un schéma GraphQL

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Vous pouvez partir d'un schéma GraphQL qui contient déjà des directives, en utilisant une commande comme celle-ci :

neptune-for-graphql \
  --input-schema-file (your GraphQL schema file with directives) \
  --create-update-aws-pipeline \
  --create-update-aws-pipeline-name (name for your new GraphQL API) \
  --create-update-aws-pipeline-neptune-endpoint  (empty Neptune database endpoint):(port number) \
  --output-resolver-query-https

Vous pouvez modifier les directives créées par l'utilitaire ou ajouter les vôtres à un schéma GraphQL. Voici quelques méthodes d'utilisation des directives :

Exécutation de l'utilitaire pour qu'il ne génère pas de mutations

Pour empêcher l'utilitaire de générer des mutations dans l'API GraphQL, utilisez l'option --output-schema-no-mutations de la commande neptune-for-graphql.

Directive @alias

La directive @alias peut être appliquée aux types de schéma ou aux champs GraphQL. Elle mappe différents noms entre la base de données orientée graphe et le schéma GraphQL. La syntaxe est la suivante :

@alias(property: (property name))

Dans l'exemple ci-dessous, airport est l'étiquette du nœud de base de données orientée graphe mappée avec le type GraphQL Airport, et desc est la propriété du nœud de graphe mappée avec le champ description (voir l'exemple des routes aériennes) :

type Airport @alias(property: "airport") {
  city: String
  description: String @alias(property: "desc")
}

Notez que la mise en forme GraphQL standard nécessite des noms de type avec la casse Pascal et des noms de champs avec la casse Camel.

Directive @relationship

La directive @relationship mappe les types GraphQL imbriqués avec les arêtes de la base de données orientée graphe. La syntaxe est la suivante :

@relationship(edgeType: (edge name), direction: (IN or OUT))

Voici un exemple de commande :

type Airport @alias(property: "airport") {
  ...
  continentContainsIn: Continent @relationship(edgeType: "contains", direction: IN)
  countryContainsIn: Country @relationship(edgeType: "contains", direction: IN)
  airportRoutesOut(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: "route", direction: OUT)
  airportRoutesIn(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: "route", direction: IN)
}

Vous trouverez des directives @relationship à la fois dans l'exemple Todo et dans l'exemple des routes aériennes.

Directives @graphQuery et @cypher

Vous pouvez définir des requêtes openCypher pour résoudre une valeur de champ, ajouter des requêtes ou ajouter des mutations. Par exemple, cela ajoute un nouveau champ outboundRoutesCount au type Airport pour compter les routes sortantes :

type Airport @alias(property: "airport") {
  ...
  outboundRoutesCount: Int @graphQuery(statement: "MATCH (this)-[r:route]->(a) RETURN count(r)")
}

Voici un exemple de nouvelles requêtes et mutations :

type Query {
  getAirportConnection(fromCode: String!, toCode: String!): Airport \
    @cypher(statement: \
      "MATCH (:airport{code: '$fromCode'})-[:route]->(this:airport)-[:route]->(:airport{code:'$toCode'})")
}

type Mutation {
  createAirport(input: AirportInput!): Airport @graphQuery(statement: "CREATE (this:airport {$input}) RETURN this")
  addRoute(fromAirportCode:String, toAirportCode:String, dist:Int): Route \
    @graphQuery(statement: \
     "MATCH (from:airport{code:'$fromAirportCode'}), (to:airport{code:'$toAirportCode'}) \
      CREATE (from)-[this:route{dist:$dist}]->(to) \
      RETURN this")
}

Notez que si vous omettez RETURN, le résolveur suppose que le mot clé this est la portée renvoyée.

Vous pouvez également ajouter une requête ou une mututation à l'aide d'une requête Gremlin :

type Query {
  getAirportWithGremlin(code:String): Airport \
    @graphQuery(statement: "g.V().has('airport', 'code', '$code').elementMap()")  # single node
  getAirportsWithGremlin: [Airport] \
    @graphQuery(statement: "g.V().hasLabel('airport').elementMap().fold()")       # list of nodes
  getCountriesCount: Int \
    @graphQuery(statement: "g.V().hasLabel('country').count()")                   # scalar
}

À l'heure actuelle, les requêtes Gremlin sont limitées à celles qui renvoient des valeurs scalaires, elementMap() pour un seul nœud ou elementMap().fold() pour une liste de nœuds.

Directive @id

La directive @id identifie le champ mappé avec l'entité de base de données orientée graphe id. Les bases de données orientées graphe telles qu'Amazon Neptune disposent toujours d'un id unique pour les nœuds et les arêtes. Celui-ci est attribué lors des importations en bloc ou est généré automatiquement. Par exemple :

type Airport {
  _id: ID! @id
  city: String
  code: String
}

Noms de type, de requête et de mutation réservés

L'utilitaire génère automatiquement des requêtes et des mutations pour créer une API GraphQL fonctionnelle. Le modèle de ces noms est reconnu par le résolveur et est réservé. Voici des exemples pour le type Airport et le type de connexion Route :

Le nom Options est réservé.

input Options {
  limit: Int
}

Les paramètres de fonction filter et options sont réservés.

type Query {
  getNodeAirports(filter: AirportInput, options: Options): [Airport]
}

Le préfixe getNode des noms de requêtes est réservé, et les préfixes des noms de mutations tels que createNode, updateNode, deleteNode, connectNode, deleteNode, updateEdge et deleteEdge sont réservés.

type Query {
  getNodeAirport(id: ID, filter: AirportInput): Airport
  getNodeAirports(filter: AirportInput): [Airport]
}

type Mutation {
  createNodeAirport(input: AirportInput!): Airport
  updateNodeAirport(id: ID!, input: AirportInput!): Airport
  deleteNodeAirport(id: ID!): Boolean
  connectNodeAirportToNodeAirportEdgeRout(from: ID!, to: ID!, edge: RouteInput!): Route
  updateEdgeRouteFromAirportToAirport(from: ID!, to: ID!, edge: RouteInput!): Route
  deleteEdgeRouteFromAirportToAirport(from: ID!, to: ID!): Boolean
}

Application de modifications au schéma GraphQL

Vous pouvez modifier le schéma source GraphQL et réexécuter l'utilitaire pour obtenir le dernier schéma de la base de données Neptune. Chaque fois que l'utilitaire découvre un nouveau schéma dans la base de données, il génère un nouveau schéma GraphQL.

Vous pouvez également modifier manuellement le schéma source GraphQL et réexécuter l'utilitaire en utilisant le schéma source comme entrée au lieu du point de terminaison de la base de données Neptune.

Enfin, vous pouvez placer vos modifications dans un fichier à l'aide de ce format JSON :

[
  {
    "type": "(GraphQL type name)",
    "field": "(GraphQL field name)",
    "action": "(remove or add)",
    "value": "(value)"
  }
]

Par exemple :

[
  {
    "type": "Airport",
    "field": "outboundRoutesCountAdd",
    "action": "add",
    "value":"outboundRoutesCountAdd: Int @graphQuery(statement: \"MATCH (this)-[r:route]->(a) RETURN count(r)\")"
  },
  {
    "type": "Mutation",
    "field": "deleteNodeVersion",
    "action": "remove",
    "value": ""
  },
  {
    "type": "Mutation",
    "field": "createNodeVersion",
    "action": "remove",
    "value": ""
  }
]

Ensuite, lorsque vous exécutez l'utilitaire sur ce fichier à l'aide du paramètre --input-schema-changes-file de la commande, l'utilitaire applique les modifications immédiatement.