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

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

Important

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

Επισκόπηση

Το GQL Query API εκθέτει ένα τελικό σημείο REST που δέχεται ερωτήματα GQL ως ωφέλιμα φορτία JSON και επιστρέφει δομημένα, πληκτρολογημένα αποτελέσματα. Υποστηρίζει τη συνέχιση της ψηφοφορίας για ερωτήματα που δεν ολοκληρώνονται κατά την αρχική αίτηση.

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

Ένα τελικό σημείο - Όλες οι λειτουργίες χρησιμοποιούν HTTP POST σε μία διεύθυνση URL.
Βάσει JSON - Τα ωφέλιμα φορτία αίτησης και απόκρισης χρησιμοποιούν JSON με εμπλουτισμένο κωδικοποίηση πληκτρολογημένων τιμών GQL.
Συνέχιση ανίχνευσης - Τα ερωτήματα μεγάλης διάρκειας μπορούν να συνεχιστούν σε πολλές αιτήσεις HTTP.
Ασφάλεια τύπου - Ισχυρή πληκτρολόγηση συμβατή με 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?beta=true

Το API ερωτήματος είναι σε έκδοση beta και δεν συνιστάται για χρήση παραγωγής. Ορίστε την απαιτούμενη beta παράμετρο ερωτήματος σε true. Η παλαιότερη preview=true παράμετρος εξακολουθεί να υποστηρίζεται για συμβατότητα με προηγούμενες εκδόσεις, αλλά χρησιμοποιείται beta=true για νέες ενσωματώσεις.

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

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

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

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

Μπορείτε να χρησιμοποιήσετε τις επιλογές εξόδου Azure CLI για να φιλτράρετε ή να μορφοποιήσετε τις αποκρίσεις από αυτές τις αιτήσεις λίστας. Αυτές οι επιλογές εκτελούνται στο πρόγραμμα-πελάτη Azure CLI. Δεν είναι παράμετροι API ερωτήματος:

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

Σημείωση

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

Παράμετροι ερωτήματος

Παράμετρος	Τύπος	Required	Περιγραφή
`beta`	δυαδική τιμή	Όχι	Ορίστε σε για `true` να χρησιμοποιήσετε το API ερωτήματος beta.
`continuationToken`	συμβολοσειρά	Όχι	Διακριτικό από τη στιγμή που `result.nextPage` ένα ερώτημα εξακολουθεί να εκτελείται. Υποβάλετε το ίδιο κείμενο ερωτήματος όταν χρησιμοποιείτε το διακριτικό.

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

Κεφαλίδα	Τιμή	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": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

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

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

Πεδίο	Τύπος	Περιγραφή
`code`	συμβολοσειρά	Κωδικός κατάστασης δημόσιου API πέντε χαρακτήρων.
`description`	συμβολοσειρά	Περιγραφή κατάστασης αναγνώσιμη από τον άνθρωπο.
`diagnostics`	αντικείμενο	Λεπτομερές διαγνωστικό αρχείο, συμπεριλαμβανομένης της κανονικής μηχανής ερωτημάτων GQLSTATUS όταν είναι διαθέσιμη.
`cause`	αντικείμενο	Προαιρετικό αντικείμενο κατάστασης υποκείμενης αιτίας.

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

Το κύριο status.code χρησιμοποιεί αυτές τις δημόσιες κατηγορίες API:

00000 - Επιτυχής ολοκλήρωση με τουλάχιστον μία σειρά.
00001 - Επιτυχής ολοκλήρωση με αποτέλεσμα που παραλείφθηκε. Προορίζεται για μελλοντική υποστήριξη DDL και DML.
01000 - Προειδοποίηση ή ενημερωτική κατάσταση.
02000 - Δεν υπάρχουν διαθέσιμες σειρές αυτήν τη στιγμή από ένα ερώτημα παραγωγής σειρών.
42000 - Σφάλμα σύνταξης, κανόνα πρόσβασης ή άλλο σφάλμα ερωτήματος που μπορεί να διορθωθεί από το χρήστη.
50000 - Σφάλμα συστήματος ή μη ταξινομημένο.

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

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

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

Σημείωση

Το _graphaneGqlStatus διαγνωστικό περιέχει την κανονική κατάσταση GQL πέντε χαρακτήρων που αναφέρεται από τη μηχανή ερωτημάτων. Κάθε διαγνωστικό μέλος με πρόθεμα υπογράμμισης περιέχει μία ή null μια τιμή GQL με κωδικοποίηση JSON. Για παράδειγμα, _graphaneGqlStatus χρησιμοποιεί STRING, ενώ τα διαγνωστικά ταξινόμησης σφαλμάτων χρησιμοποιούν BOOL. Ανατρέξτε στο θέμα Τύποι τιμών και κωδικοποίηση.

Προκαλεί

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

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

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

Η κύρια κατάσταση είναι η πιο κρίσιμη καταγεγραμμένη κατάσταση. Κάθε πρόσθετη κατάσταση και ένθετη αιτία έχει τον δικό της δημόσιο κώδικα API και κανονικό διαγνωστικό GQLSTATUS.

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

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

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

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

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

Ερωτήματα μεγάλης διάρκειας

Εάν ένα ερώτημα δεν ολοκληρωθεί κατά τη διάρκεια της τρέχουσας αίτησης HTTP, το API επιστρέφει HTTP 200 με δημόσιο κωδικό 02000κατάστασης , έναν κενό πίνακα και ένα nextPage διακριτικό:

{
  "status": {
    "code": "02000",
    "description": "No data available, retry with continuation token"
  },
  "result": {
    "kind": "TABLE",
    "columns": [],
    "data": [],
    "nextPage": "{continuationToken}"
  }
}

Κάντε δημοσκόπηση για ολοκλήρωση στέλνοντας το ίδιο σώμα αιτήματος και προσθέτοντας το διακριτικό στη διεύθυνση URL:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true&continuationToken={continuationToken}

Αντιμετωπίστε nextPage ως αδιαφανή τιμή. Κωδικοποιήστε το ακριβώς μία φορά σύμφωνα με το continuationToken RFC 3986 πριν το χρησιμοποιήσετε ως τιμή παραμέτρου ερωτήματος. Μην αποκωδικοποιείτε, επιθεωρείτε ή τροποποιείτε το διακριτικό.

Συνεχίστε έως ότου η απάντηση δεν περιέχει nextPageπλέον . Η εκτέλεση ερωτήματος μπορεί να συνεχιστεί για έως και 20 λεπτά από την αρχική αίτηση. Εάν υπερβεί αυτήν τη συνολική διάρκεια, το API επιστρέφει HTTP 408 με κωδικό QueryTimeoutσφάλματος .

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

Graph περικόπτει μια απόκριση ερωτήματος όταν η εσωτερική δυαδική αναπαράστασή της υπερβαίνει τα 64 MB. Το API επιστρέφει τις γραμμές που ταιριάζουν και προσθέτει μια κατάσταση στο additionalStatuses. Η πρόσθετη κατάσταση χρησιμοποιεί δημόσιο κώδικα 01000 και διατηρεί την κανονική κατάσταση GQLSTATUS 01M11 στο _graphaneGqlStatus.

Η περικοπή δεν παράγει ένα διακριτικό nextPage για τις γραμμές που παραλείπονται. Περιορίστε το ερώτημα με φίλτρα, συγκεκριμένες προβολές ή LIMITκαι εκτελέστε το ξανά.

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

Το σχήμα απόκρισης μπορεί να αντιπροσωπεύει μια λειτουργία της οποίας η δήλωση δεν παράγει ποτέ σειρές, ανεξάρτητα από τα δεδομένα ή το αποτέλεσμα της αξιολόγησης. Αυτό το αποτέλεσμα χρησιμοποιεί κωδικό 00001κατάστασης:

{
  "kind": "NOTHING"
}

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

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

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

Το 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"]
}

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

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

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

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

{
  "kind": "TABLE",
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "amount", "gqlType": "INT64", "jsonType": "number|string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "object"}
  ],
  "data": [
    {
      "name": "Alice",
      "amount": "123",
      "mixed": {"gqlType": "INT64", "value": "1"}
    }
  ]
}

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

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

Η κατάσταση HTTP και η κατάσταση GQL περιγράφουν διαφορετικά επίπεδα της απόκρισης:

Κατάσταση HTTP	Έννοια
200	Το API επεξεργάστηκε το αίτημα. Επιθεώρηση `status.code` επειδή το αποτέλεσμα μπορεί να αντιπροσωπεύει επιτυχία, χωρίς γραμμές, ένα ερώτημα που βρίσκεται ακόμη σε εξέλιξη ή ένα σφάλμα ερωτήματος που μπορεί να διορθωθεί από το χρήστη.
408	Η εκτέλεση του ερωτήματος υπερέβη το συνολικό χρονικό όριο των 20 λεπτών. Ο κωδικός σφάλματος είναι `QueryTimeout`.
429	Έγινε υπέρβαση του ορίου επιτοκίου υπηρεσίας. Περιμένετε τη διάρκεια στην `Retry-After` κεφαλίδα πριν προσπαθήσετε ξανά.
499	Ο καλών ακύρωσε το αίτημα. Ο κωδικός σφάλματος είναι `ClientCancelled`.
Άλλα 4xx ή 5xx	Το αίτημα ή η υπηρεσία απέτυχε πριν επιστρέψει ένα αποτέλεσμα εκτέλεσης GQL. Ελέγξτε την απόκριση σφάλματος HTTP.

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

Ένα σφάλμα σε επίπεδο εφαρμογής μπορεί να επιστρέψει HTTP 200 με πληροφορίες σφάλματος στο αντικείμενο κατάστασης. Για παράδειγμα, η διαίρεση με το μηδέν χρησιμοποιεί τον δημόσιο κώδικα 42000 API και διατηρεί την κανονική κατάσταση GQLSTATUS 22012 στο διαγνωστικό αρχείο:

{
  "status": {
    "code": "42000",
    "description": "error: data exception - division by zero",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "22012"
      },
      "_graphaneIsUserError": {
        "gqlType": "BOOL",
        "value": true
      },
      "_graphaneIsTransientError": {
        "gqlType": "BOOL",
        "value": false
      }
    }
  }
}

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

Για να προσδιορίσετε το ευρύ αποτέλεσμα, ελέγξτε το κοινό status.code. Χρησιμοποιήστε το _graphaneGqlStatus όταν η εφαρμογή σας χρειάζεται να διακρίνει μια συγκεκριμένη συνθήκη μηχανισμού ερωτήματος, όπως η αριθμητική υπερχείλιση (22003) από τη διαίρεση με το μηδέν (22012).

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

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

az rest --method post --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=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?beta=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 εγγενώς.
Χειρισμός ειδικών τιμών κινητής υποδιαστολής - Το API σειριοποιεί το θετικό άπειρο, το αρνητικό άπειρο, τον αριθμό και το αρνητικό μηδέν ως "Inf", "-Inf", "NaN", και "-0".
Χειρισμός τιμών null - Η τιμή null JSON αντιπροσωπεύει την τιμή null GQL.

Σχόλια

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

Last updated on 2026-09-29

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

Επισκόπηση

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

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

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

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

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

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

Παράμετροι ερωτήματος

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

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

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

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

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

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

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

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

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

Προκαλεί

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

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

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

Ερωτήματα μεγάλης διάρκειας

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

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

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

Δομή τιμών

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

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

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

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

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

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

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

Λίστες

Διαδρομές

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

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

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

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

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

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

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

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

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

Ασφάλεια

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

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

Σχόλια

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