Αναφορά API ερωτήματος GQL

Σημείωση

Αυτή η δυνατότητα βρίσκεται αυτήν τη στιγμή σε δημόσια προεπισκόπηση. Αυτή η προεπισκόπηση παρέχεται χωρίς σύμβαση παροχής υπηρεσιών και δεν συνιστάται για φόρτους εργασίας παραγωγής. Ορισμένες δυνατότητες ενδέχεται να μην υποστηρίζονται ή να έχουν περιορισμένες δυνατότητες. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Χρήση συμψηφικών όρων χρήσης για Microsoft Azure προεπισκοπήσεις.

Εκτελέστε ερωτήματα GQL σε γραφήματα ιδιοτήτων στο Microsoft Fabric χρησιμοποιώντας ένα RESTful HTTP API. Αυτή η αναφορά περιγράφει τη σύμβαση HTTP: μορφές αίτησης και απόκρισης, έλεγχος ταυτότητας, κωδικοποίηση αποτελεσμάτων JSON και χειρισμός σφαλμάτων.

Important

Αυτό το άρθρο χρησιμοποιεί αποκλειστικά το σύνολο δεδομένων παραδειγμάτων γραφήματος κοινωνικού δικτύου.

Επισκόπηση

Το API ερωτήματος GQL είναι ένα μοναδικό τελικό σημείο (RPC μέσω HTTP) που αποδέχεται ερωτήματα GQL ως ωφέλιμα φορτία JSON και επιστρέφει δομημένα, πληκτρολογοποιημένα αποτελέσματα. Το API είναι χωρίς κατάσταση κατάστασης, χειρίζεται τον έλεγχο ταυτότητας και παρέχει ολοκληρωμένες αναφορές σφαλμάτων.

Δυνατότητες κλειδιά

Ένα τελικό σημείο - Όλες οι λειτουργίες χρησιμοποιούν HTTP POST σε μία διεύθυνση URL.
Βάσει JSON - Τα ωφέλιμα φορτία αίτησης και απόκρισης χρησιμοποιούν JSON με εμπλουτισμένο κωδικοποίηση πληκτρολογημένων τιμών GQL.
Χωρίς κατάσταση κατάστασης κατάστασης μέλους - Δεν απαιτείται κατάσταση περιόδου λειτουργίας μεταξύ των αιτήσεων.
Ασφάλεια τύπου - Ισχυρή πληκτρολόγηση συμβατή με GQL με διακριτικές ενώσεις για αναπαράσταση αξίας.

Προαπαιτούμενα στοιχεία

Χρειάζεστε ένα γράφημα που περιέχει δεδομένα, συμπεριλαμβανομένων των κόδων και των άκρων (σχέσεις). Ανατρέξτε στο γράφημα γρήγορης εκκίνησης για να δημιουργήσετε και να φορτώσετε ένα δείγμα γραφήματος.
Θα πρέπει να είστε εξοικειωμένοι με τα γραφήματα ιδιοτήτων και μια βασική κατανόηση του GQL, συμπεριλαμβανομένης της δομής των αποτελεσμάτων εκτέλεσης και των αποτελεσμάτων.
Πρέπει να εγκαταστήσετε και να ρυθμίσετε το εργαλείο Azure CLIaz για να εισέλθετε στον οργανισμό σας. Τα παραδείγματα γραμμής εντολών σε αυτό το άρθρο προϋποθέτουν τη χρήση ενός κελύφους γραμμής εντολών συμβατό με POSIX, όπως το bash.

Έλεγχος ταυτότητας

Το API ερωτήματος GQL απαιτεί έλεγχο ταυτότητας μέσω διακριτικών φορέα.

Συμπεριλάβετε το διακριτικό πρόσβασης στην κεφαλίδα Εξουσιοδότηση κάθε αίτησης:

Authorization: Bearer <your-access-token>

Σε γενικές γραμμές, μπορείτε να λάβετε διακριτικά φορέα χρησιμοποιώντας το Microsoft Authentication Library (MSAL) ή άλλες ροές ελέγχου ταυτότητας που είναι συμβατές με Microsoft Entra.

Τα διακριτικά φορέα λαμβάνονται συνήθως μέσω δύο κύριων διαδρομών:

Πρόσβαση με ανάθεση από τον χρήστη

Μπορείτε να λάβετε διακριτικά φορέα για κλήσεις εξυπηρέτησης με ανάθεση από τον χρήστη από τη γραμμή εντολών μέσω του εργαλείου Azure CLI tool az.

Λάβετε ένα διακριτικό φορέα για κλήσεις με ανάθεση από τον χρήστη από τη γραμμή εντολών ως εξής:

Εκτελέστε το az login
Τότε az account get-access-token --resource https://api.fabric.microsoft.com

Αυτό χρησιμοποιεί το εργαλείο Azure CLIaz.

Όταν χρησιμοποιείτε το az rest για την εκτέλεση αιτήσεων, τα διακριτικά φορέα λαμβάνονται αυτόματα.

Πρόσβαση εφαρμογής

Μπορείτε να λάβετε διακριτικά φορέα για αιτήσεις που έχουν καταχωρηθεί στο Microsoft Entra. Συμβουλευτείτε τον οδηγό γρήγορης εκκίνησης API Fabric για περισσότερες λεπτομέρειες.

Τελικό σημείο API

Το API χρησιμοποιεί ένα μοναδικό τελικό σημείο που αποδέχεται όλες τις λειτουργίες ερωτήματος:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true

Για να αποκτήσετε το για τον {workspaceId} χώρο εργασίας σας, μπορείτε να καταχωρήσετε όλους τους διαθέσιμους χώρους εργασίας χρησιμοποιώντας az restτο :

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces"

Για να λάβετε το {graphId}, μπορείτε να παραθέσετε όλα τα διαθέσιμα γραφήματα σε έναν χώρο εργασίας χρησιμοποιώντας το az rest:

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels"

Μπορείτε να χρησιμοποιήσετε περισσότερες παραμέτρους για να περιορίσετε περαιτέρω τα αποτελέσματα ερωτημάτων:

--query 'value[?displayName=='My Workspace'] για την παράθεση μόνο στοιχείων με ένα displayNameMy Workspace.
--query 'value[starts_with(?displayName='My')] Για την παράθεση μόνο των στοιχείων των οποίων η displayName ξεκινά με My.
--query '{query}' Για την παράθεση μόνο των στοιχείων που συμφωνούν με το παρεχόμενο JMESPath {query}. Ανατρέξτε στην τεκμηρίωση Azure CLI στο JMESPath σχετικά με την υποστηριζόμενη σύνταξη για το {query}.
-o table για την παραγωγή ενός αποτελέσματος πίνακα.

Σημείωση

Ανατρέξτε στην ενότητα σχετικά με τη χρήση az-rest ή την ενότητα σχετικά με τη χρήση της μπούκλας για τον τρόπο εκτέλεσης ερωτημάτων μέσω του τελικού σημείου API από ένα κέλυφος γραμμής εντολών.

Επικεφαλίδες αιτήματος

Κεφαλίδα	Τιμή	Required
`Content-Type`	`application/json`	Όχι
`Accept`	`application/json`	Όχι
`Authorization`	`Bearer <token>`	Όχι

Μορφή αίτησης

Όλες οι αιτήσεις χρησιμοποιούν HTTP POST με ωφέλιμο φορτίο JSON.

Βασική δομή αιτήσεων

{
  "query": "MATCH (n) RETURN n LIMIT 100"
}

Πεδία αίτησης

Πεδίο	Τύπος	Required	Περιγραφή
`query`	συμβολοσειρά	Όχι	Το ερώτημα GQL για εκτέλεση

Μορφή απάντησης

Όλες οι αποκρίσεις για επιτυχημένες αιτήσεις χρησιμοποιούν την κατάσταση HTTP 200 με ωφέλιμο φορτίο JSON που περιέχει την κατάσταση εκτέλεσης και τα αποτελέσματα.

Δομή απόκρισης

{
  "status": {
    "code": "00000",
    "description": "note: successful completion", 
    "diagnostics": {
      "OPERATION": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Αντικείμενο κατάστασης

Κάθε απόκριση περιλαμβάνει ένα αντικείμενο κατάστασης με πληροφορίες εκτέλεσης:

Πεδίο	Τύπος	Περιγραφή
`code`	συμβολοσειρά	κωδικός κατάστασης έξι χαρακτήρων (000000 = επιτυχία)
`description`	συμβολοσειρά	Μήνυμα κατάστασης αναγνώσιμη από τον άνθρωπο
`diagnostics`	αντικείμενο	Λεπτομερείς διαγνωστικές εγγραφές
`cause`	αντικείμενο	Προαιρετικό αντικείμενο κατάστασης υποκείμενης αιτίας

Κωδικοί κατάστασης

Οι κωδικοί κατάστασης ακολουθούν ένα ιεραρχικό μοτίβο:

00xxxx - Ολοκληρώθηκε η επιτυχία
01xxxx - Επιτυχία με προειδοποιήσεις
02xxxx - Επιτυχία χωρίς δεδομένα
03xxxx - Επιτυχία με τις πληροφορίες
04xxxx και νεότερες εκδόσεις - Σφάλματα και συνθήκες εξαίρεσης

Για περισσότερες πληροφορίες, ανατρέξτε στην αναφορά κωδικών κατάστασης GQL.

Διαγνωστικές εγγραφές

Οι εγγραφές διαγνωστικού ελέγχου μπορεί να περιέχουν άλλα ζεύγη κλειδιού-τιμής που περιγράφουν περαιτέρω λεπτομερώς το αντικείμενο κατάστασης. Τα κλειδιά που ξεκινούν με έναν χαρακτήρα υπογράμμισης (_) αφορούν συγκεκριμένα το γράφημα. Το πρότυπο GQL ορίζει όλα τα άλλα κλειδιά.

Σημείωση

Οι τιμές στην εγγραφή διαγνωστικού ελέγχου κλειδιών που αφορούν συγκεκριμένα το γράφημα είναι τιμές GQL με κωδικοποίηση JSON. Ανατρέξτε στο θέμα Τύποι τιμών και κωδικοποίηση.

Προκαλεί

Τα αντικείμενα κατάστασης περιλαμβάνουν ένα προαιρετικό cause πεδίο όταν είναι γνωστή μια υποκείμενη αιτία.

Άλλα αντικείμενα κατάστασης

Ορισμένα αποτελέσματα μπορούν να αναφέρουν άλλα αντικείμενα κατάστασης ως λίστα στο πεδίο (προαιρετικό additionalStatuses ).

Σε αυτή την περίπτωση, το αντικείμενο κύριας κατάστασης προσδιορίζεται πάντα ότι είναι το πιο κρίσιμο αντικείμενο κατάστασης (όπως μια συνθήκη εξαίρεσης), όπως ορίζεται από το πρότυπο GQL.

Τύποι αποτελεσμάτων

Τα αποτελέσματα χρησιμοποιούν ένα διακριτικό μοτίβο ένωσης με το kind πεδίο:

Αποτελέσματα πίνακα

Για ερωτήματα που επιστρέφουν δεδομένα σε μορφή πίνακα:

{
  "kind": "TABLE",
  "columns": [
    {
      "name": "name",
      "gqlType": "STRING",
      "jsonType": "string"
    },
    {
      "name": "age",
      "gqlType": "INT32",
      "jsonType": "number"
    }
  ],
  "isOrdered": true,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

Παραλείπονται αποτελέσματα

Για λειτουργίες που δεν επιστρέφουν δεδομένα (για παράδειγμα, ενημερώσεις καταλόγου ή/και δεδομένων):

{
  "kind": "NOTHING"
}

Τύποι τιμών και κωδικοποίηση

Το API χρησιμοποιεί ένα σύστημα εμπλουτισμένου τύπου για την αναπαράσταση τιμών GQL με ακριβή σημασιολογία. Η μορφή JSON των τιμών GQL ακολουθεί ένα διακριτικό πρότυπο ένωσης.

Σημείωση

Η μορφή JSON των αποτελεσμάτων σε μορφή πίνακα συνειδητοποιεί το διακριτικό μοτίβο ένωσης διαχωρίζοντας και gqlType επιτυγχάνοντας value μια πιο συμπαγή αναπαράσταση. Ανατρέξτε στο θέμα Βελτιστοποίηση σειριοποίησης πίνακα.

Δομή τιμών

{
  "gqlType": "TYPE_NAME",
  "value": <type-specific-value>
}

Στοιχειώδεις τύποι

Τύπος GQL	Παράδειγμα	Περιγραφή
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Εγγενής δυαδική τιμή JSON
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	Συμβολοσειρά UTF-8

Αριθμητικοί τύποι

Τύποι ακέραιων

Τύπος GQL	Περιοχή	Σειριοποίηση JSON	Παράδειγμα
`INT64`	-2⁶³ έως 2⁶³-1	Αριθμός ή συμβολοσειρά*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 έως 2⁶⁴-1	Αριθμός ή συμβολοσειρά*	`{"gqlType": "UINT64", "value": 18467}`

Οι μεγάλοι ακέραιοι χρήστες εκτός της ασφαλούς περιοχής της JavaScript (-9.007.199.254.740.991 έως 9.007.199.254.740.991) σειριοποιούνται ως συμβολοσειρές:

{"gqlType": "INT64", "value": "9223372036854775807"}
{"gqlType": "UINT64", "value": "18446744073709551615"}

Τύποι κινητής υποδιαστολής

Τύπος GQL	Περιοχή	Σειριοποίηση JSON	Παράδειγμα
`FLOAT64`	Δυαδικό IEEE 75464	Αριθμός ή συμβολοσειρά JSON	`{"gqlType": "FLOAT64", "value": 3.14}`

Οι τιμές κινητής υποδιαστολής υποστηρίζουν ειδικές τιμές IEEE 754:

{"gqlType": "FLOAT64", "value": "Inf"}
{"gqlType": "FLOAT64", "value": "-Inf"}
{"gqlType": "FLOAT64", "value": "NaN"}
{"gqlType": "FLOAT64", "value": "-0"}

Χρονικοί τύποι

Οι υποστηριζόμενοι χρονικοί τύποι χρησιμοποιούν μορφές συμβολοσειρών ISO 8601:

Τύπος GQL	Format	Παράδειγμα
`ZONED DATETIME`	ΕΕΕΕ-ΜΜ-DDTHH:ΜΜ:SS[.ffffff]±HH:ΜΜ	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Τύποι αναφοράς στοιχείων γραφήματος

Τύπος GQL	Περιγραφή	Παράδειγμα
`NODE`	Αναφορά κόμβου γραφήματος	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Αναφορά άκρου γραφήματος	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Σύνθετοι τύποι

Οι σύνθετοι τύποι αποτελούνται από άλλες τιμές GQL.

Λίστες

Οι λίστες περιέχουν πίνακες τιμών που επιδέχεται τιμές null με συνεπείς τύπους στοιχείων:

{
  "gqlType": "LIST<INT64>",
  "value": [1, 2, null, 4, 5]
}

Ειδικοί τύποι λίστας:

LIST<ANY> - Μεικτοί τύποι (κάθε στοιχείο περιλαμβάνει πληροφορίες πλήρους τύπου)
LIST<NULL> - Επιτρέπονται μόνο τιμές null
LIST<NOTHING> - Πάντα κενός πίνακας

Διαδρομές

Οι διαδρομές κωδικοποιούνται ως λίστες τιμών αναφοράς στοιχείων γραφήματος.

{
    "gqlType": "PATH",
    "value": ["node1", "edge1", "node2"]
}

Ανατρέξτε στο θέμα Βελτιστοποίηση σειριοποίησης πίνακα.

Βελτιστοποίηση σειριοποίησης πίνακα

Για τα αποτελέσματα του πίνακα, η σειριοποίηση τιμών βελτιστοποιείται με βάση τις πληροφορίες τύπου στήλης:

Γνωστοί τύποι - Μόνο η ανεπεξέργαστα τιμή σειριοποιείται
ΣΤΗΛΕΣ - Αντικείμενο πλήρους τιμής με διάκριση τύπου

{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Χειρισμός σφαλμάτων

Σφάλματα μεταφοράς

Τα σφάλματα μεταφοράς δικτύου και HTTP έχουν ως αποτέλεσμα τυπικούς κωδικούς κατάστασης σφάλματος HTTP (4xx, 5xx).

Σφάλματα εφαρμογής

Τα σφάλματα σε επίπεδο εφαρμογής επιστρέφουν πάντα HTTP 200 με πληροφορίες σφάλματος στο αντικείμενο κατάστασης:

{
  "status": {
    "code": "42001",
    "description": "error: syntax error or access rule violation",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_errorLocation": {
        "gqlType": "STRING",
        "value": "line 1, column 15"
      }
    },
    "cause": {
      "code": "22007",
      "description": "error: data exception - invalid date, time, or, datetime
format",
      "diagnostics": {
        "OPERATION": "query",
        "OPERATION_CODE": "0",
        "CURRENT_SCHEMA": "/"
      }
    }
  }
}

Έλεγχος κατάστασης

Για να προσδιορίσετε την επιτυχία, ελέγξτε τον κωδικό κατάστασης:

Κωδικοί που ξεκινούν με 00, 01, 0203 υποδεικνύουν επιτυχία (με πιθανές προειδοποιήσεις)
Όλοι οι άλλοι κωδικοί υποδεικνύουν σφάλματα

Πλήρες παράδειγμα με az rest

Εκτελέστε ένα ερώτημα χρησιμοποιώντας την εντολή για να αποφύγετε την az rest απόκτηση διακριτικών κομιστή με μη αυτόματο τρόπο, όπως:

az rest --method post --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
--headers "Content-Type=application/json" "Accept=application/json" \
--resource "https://api.fabric.microsoft.com" \
--body '{ 
  "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
}'

Πλήρες παράδειγμα με μπούκλες

Το παράδειγμα σε αυτήν την ενότητα χρησιμοποιεί το εργαλείο για την curl εκτέλεση αιτήσεων HTTPS από το κέλυφος.

Υποθέτουμε ότι έχετε ένα έγκυρο διακριτικό πρόσβασης αποθηκευμένο σε μια μεταβλητή κελύφους, όπως:

export ACCESS_TOKEN="your-access-token-here"

Συμβουλή

Ανατρέξτε στην ενότητα σχετικά με τον έλεγχο ταυτότητας για τον τρόπο απόκτησης ενός έγκυρου διακριτικού φορέα.

Εκτελέστε ένα ερώτημα όπως:

curl -X POST "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
  }'

Βέλτιστες πρακτικές

Ακολουθήστε αυτές τις βέλτιστες πρακτικές κατά τη χρήση του API ερωτημάτων GQL.

Χειρισμός σφαλμάτων

Να ελέγχετε πάντα τους κωδικούς κατάστασης - Μην υποθέσετε επιτυχία βάσει HTTP 200.
Λεπτομέρειες σφάλματος ανάλυσης - Χρησιμοποιήστε διαγνωστικά και προκαλέστε αλυσιδωτές αλυσίδες για τον εντοπισμό σφαλμάτων.

Ασφάλεια

Χρήση HTTPS - Να μην στέλνετε ποτέ διακριτικά ελέγχου ταυτότητας μέσω μη κρυπτογραφημένων συνδέσεων.
Εκ περιτροπής διακριτικά - Υλοποιήστε κατάλληλο χειρισμό ανανέωσης και λήξης διακριτικών.
Επικύρωση εισόδων - Απολυμαίνοντας και σωστά διαφυγή από οποιεσδήποτε παραμέτρους ερωτήματος που παρέχονται από τον χρήστη, οι οποίες εισάγονται στο ερώτημα.

Αναπαράσταση τιμής

Χειρισμός μεγάλων ακέραιων τιμών - Οι ακέραιοι κωδικοποιούνται ως συμβολοσειρές εάν δεν μπορούν να αναπαρασταθούν ως αριθμοί JSON εγγενώς.
Χειρισμός ειδικών τιμών κινητής υποδιαστολής - Οι τιμές κινητής υποδιαστολής που επιστρέφονται από ερωτήματα μπορεί να είναι Infinityτιμές , -Infinityή NaN (όχι αριθμός).
Χειρισμός τιμών null - Η τιμή null JSON αντιπροσωπεύει την τιμή null GQL.

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-03-12

Αναφορά API ερωτήματος GQL

Επισκόπηση

Δυνατότητες κλειδιά

Προαπαιτούμενα στοιχεία

Έλεγχος ταυτότητας

Πρόσβαση με ανάθεση από τον χρήστη

Πρόσβαση εφαρμογής

Τελικό σημείο API

Επικεφαλίδες αιτήματος

Μορφή αίτησης

Βασική δομή αιτήσεων

Πεδία αίτησης

Μορφή απάντησης

Δομή απόκρισης

Αντικείμενο κατάστασης

Κωδικοί κατάστασης

Διαγνωστικές εγγραφές

Προκαλεί

Άλλα αντικείμενα κατάστασης

Τύποι αποτελεσμάτων

Αποτελέσματα πίνακα

Παραλείπονται αποτελέσματα

Τύποι τιμών και κωδικοποίηση

Δομή τιμών

Στοιχειώδεις τύποι

Αριθμητικοί τύποι

Τύποι ακέραιων

Τύποι κινητής υποδιαστολής

Χρονικοί τύποι

Τύποι αναφοράς στοιχείων γραφήματος

Σύνθετοι τύποι

Λίστες

Διαδρομές

Βελτιστοποίηση σειριοποίησης πίνακα

Χειρισμός σφαλμάτων

Σφάλματα μεταφοράς

Σφάλματα εφαρμογής

Έλεγχος κατάστασης

Πλήρες παράδειγμα με az rest

Πλήρες παράδειγμα με μπούκλες

Βέλτιστες πρακτικές

Χειρισμός σφαλμάτων

Ασφάλεια

Αναπαράσταση τιμής

Σχετικό περιεχόμενο

Σχόλια

Πρόσθετοι πόροι