API Fabric για ενδοσκόπηση GraphQL και εξαγωγή σχήματος

Όταν δημιουργείτε εφαρμογές ή ενσωματώνετε εξωτερικά εργαλεία με το Fabric API για GraphQL, πρέπει να κατανοήσετε τη δομή του API σας—ποιοι τύποι είναι διαθέσιμοι, ποια πεδία περιέχουν και πώς σχετίζονται μεταξύ τους. Είτε δημιουργείτε κώδικα πελάτη, είτε δημιουργείτε τεκμηρίωση είτε διαμορφώνετε εργαλεία διαχείρισης API, η πρόσβαση στον ορισμό του σχήματος είναι απαραίτητη.

Το Fabric API για GraphQL παρέχει δύο συμπληρωματικούς μηχανισμούς για την ανάκτηση πληροφοριών σχήματος: ενδοσκόπηση για ερωτήματα χρόνου εκτέλεσης μέσω προγραμματισμού και εξαγωγή σχήματος για τη λήψη ενός πλήρους αρχείου σχήματος. Και οι δύο μέθοδοι σάς δίνουν πρόσβαση στο ίδιο υποκείμενο σχήμα, αλλά η καθεμία εξυπηρετεί διαφορετικές ροές εργασίας και περιπτώσεις χρήσης.

Φιλοδώρημα

Θέλετε να δείτε την ενδοσκόπηση σε δράση; Δοκιμάστε το πρόγραμμα εκμάθησης Σύνδεση πρακτόρων AI στο Fabric API για GraphQL με έναν τοπικό διακομιστή Model Context Protocol (MCP). Αυτός ο πρακτικός οδηγός δείχνει πώς οι πράκτορες AI χρησιμοποιούν την ενδοσκόπηση για να ανακαλύψουν και να υποβάλουν αυτόματα ερωτήματα στα δεδομένα Fabric χρησιμοποιώντας φυσική γλώσσα.

Ποιος χρησιμοποιεί την ενδοσκόπηση και την εξαγωγή σχημάτων

Η ενδοσκόπηση και η εξαγωγή σχημάτων είναι πολύτιμες για:

Προγραμματιστές εφαρμογών που δημιουργούν προγράμματα-πελάτες που καταναλώνουν δεδομένα Fabric και πρέπει να δημιουργήσουν κώδικα ασφαλή για τον τύπο
Οι συμβάλλοντες χώρου εργασίας Fabric κατανοούν τις διαθέσιμες δομές δεδομένων και δοκιμάζουν την πρόσβαση σε δεδομένα
Εργαλεία ανάπτυξης και IDE που παρέχουν αυτόματη συμπλήρωση και IntelliSense for Fabric GraphQL API
Ενσωματώσεις Azure API Management που δρομολογούν και ασφαλίζουν την κυκλοφορία Fabric GraphQL σε εταιρικό επίπεδο
Διαχειριστές Fabric που ελέγχουν εκτεθειμένες δομές δεδομένων και επικυρώνουν ελέγχους πρόσβασης
Πράκτορες και βοηθοί τεχνητής νοημοσύνης που χρησιμοποιούν το Model Context Protocol (MCP) για να ανακαλύψουν και να αναζητήσουν δεδομένα Fabric με φυσικό τρόπο
Οι προγραμματιστές του Power Platform κατανοούν τα σχήματα δεδομένων Fabric πριν από τη δημιουργία ενοποιήσεων
Διοχετεύσεις CI/CD που παρακολουθούν εκδόσεις σχήματος Fabric GraphQL και επικυρώνουν τη συμβατότητα σε περιβάλλοντα

Επιλέξτε ενδοσκόπηση όταν χρειάζεται να υποβάλετε ερωτήματα σε πληροφορίες σχήματος μέσω προγραμματισμού κατά το χρόνο εκτέλεσης, όπως η τροφοδοσία εργαλείων ανάπτυξης, η ενεργοποίηση πρακτόρων τεχνητής νοημοσύνης ή η υλοποίηση δυναμικών λειτουργιών πελάτη. Επιλέξτε εξαγωγή σχήματος όταν χρειάζεστε ένα πλήρες αρχείο σχήματος για χρήση εκτός σύνδεσης, έλεγχο έκδοσης, ενοποίηση πύλης API ή κοινή χρήση με εξωτερικές ομάδες.

Ενδοσκόπηση: Ζητήστε το σχήμα σας μέσω προγραμματισμού χρησιμοποιώντας το σύστημα ενδοσκόπησης GraphQL, το οποίο αποτελεί μέρος του προτύπου GraphQL. Τα ερωτήματα ενδοσκόπησης σάς επιτρέπουν να ανακαλύψετε τύπους, πεδία και σχέσεις δυναμικά και τροφοδοτούν πολλά εργαλεία ανάπτυξης GraphQL.
Εξαγωγή σχήματος: Κατεβάστε ένα πλήρες αρχείο SDL (GraphQL Schema Definition Language) που περιέχει ολόκληρο τον ορισμό σχήματος για χρήση εκτός σύνδεσης, κοινή χρήση ή ενσωμάτωση εργαλείων.

Ενδοσκόπηση

Από προεπιλογή, η ενδοσκόπηση είναι απενεργοποιημένη στο API για στοιχεία GraphQL. Αυτή η ρύθμιση μπορεί να αλλάξει μόνο από διαχειριστές χώρου εργασίας. Όλοι οι άλλοι χρήστες θα βλέπουν ένα απενεργοποιημένο ρυθμιστικό.

Για να ενεργοποιήσετε την ενδοσκόπηση:

Επιλέξτε το εικονίδιο με το γρανάζι Ρυθμίσεις API στο επάνω μενού.
Από το αριστερό πλαίσιο πλοήγησης, επιλέξτε τη σελίδα Ενδοσκόπηση .
Επιλέξτε την εναλλαγή για να ενεργοποιήσετε την ενδοσκόπηση. Η ενεργοποίηση της ενδοσκόπησης εκθέτει τις πληροφορίες σχήματος σε όλους τους χρήστες με πρόσβαση στο τελικό σημείο API.
Εμφανίζεται ένα παράθυρο διαλόγου επιβεβαίωσης. Επιλέξτε Επιβεβαίωση για να ενεργοποιήσετε την ενδοσκόπηση ή Ακύρωση για να την αφήσετε απενεργοποιημένη.

Παράδειγμα ερωτήματος ενδοσκόπησης

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

Δημιουργήστε ένα νέο ερώτημα στον επεξεργαστή GraphQL. Επιλέξτε το εικονίδιο συν + δίπλα στις υπάρχουσες καρτέλες για να ανοίξετε μια νέα καρτέλα ερωτήματος.
Εισαγάγετε το ακόλουθο ερώτημα ενδοσκόπησης στο πρόγραμμα επεξεργασίας:
```
query {
    __schema {
        types{
            name
        }
    }
}
```
Επιλέξτε το κουμπί Εκτέλεση για να εκτελέσετε το ερώτημα.
Το παράθυρο αποτελεσμάτων εμφανίζει μια λίστα με όλους τους τύπους που ορίζονται στο σχήμα.

Τα ερωτήματα ενδοσκόπησης μπορούν να επιστρέψουν μεγάλες ποσότητες πληροφοριών. Μπορείτε να περιορίσετε το εύρος αυτού που ρωτάτε με το να είστε πιο συγκεκριμένοι στο αίτημα ενδοσκόπησης. Για παράδειγμα, αντί να υποβάλετε ερωτήματα σε όλους τους τύπους, μπορείτε να υποβάλετε ερώτημα σε έναν συγκεκριμένο τύπο:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

Η εκτέλεση του ερωτήματος επιστρέφει λεπτομερείς πληροφορίες σχετικά με τον ProductCategory τύπο:

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

Τα κοινά μοτίβα φιλτραρίσματος κατά την επεξεργασία των αποτελεσμάτων της ενδοσκόπησης περιλαμβάνουν:

Εξαιρούνται οι τύποι που ξεκινούν με διπλές υπογράμμιση (__), οι οποίοι είναι τύποι συστήματος GraphQL
Συμπεριλαμβανομένων τύπων που ξεκινούν με συγκεκριμένα προθέματα όπως ProductCategory

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

Εξαγωγή σχήματος

Όταν χρειάζεστε ένα πλήρες, εκτός σύνδεσης αντίγραφο του ορισμού σχήματος, χρησιμοποιήστε τη δυνατότητα εξαγωγής σχήματος απευθείας από την πύλη Fabric. Ανοίξτε το API για το GraphQL και επιλέξτε Εξαγωγή σχήματος από τη γραμμή εργαλείων. Το πρόγραμμα περιήγησής σας κατεβάζει ένα αρχείο SDL (Schema Definition Language) που περιέχει τον πλήρη ορισμό του σχήματος.

Κατανόηση του αρχείου SDL

Το εξαγόμενο αρχείο χρησιμοποιεί τη γλώσσα ορισμού σχήματος (SDL) της GraphQL, μια μορφή αναγνώσιμη από τον άνθρωπο που καθορίζει τους τύπους, τα πεδία και τις σχέσεις του API σας. Το αρχείο SDL περιλαμβάνει:

Τύποι αντικειμένων που αντιπροσωπεύουν τις οντότητες δεδομένων σας με τα πεδία τους
Λειτουργίες ερωτημάτων που καθορίζουν τον τρόπο ανάκτησης δεδομένων
Λειτουργίες μετάλλαξης για δημιουργία, ενημέρωση ή διαγραφή δεδομένων
Ορίσματα πεδίων που καθορίζουν τις παραμέτρους εισόδου και τους τύπους τους
Περιγραφές τύπων που παρέχουν τεκμηρίωση για κάθε στοιχείο

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

Χρήση του εξαγόμενου σχήματος

Οι συνήθεις περιπτώσεις χρήσης για το εξαγόμενο αρχείο SDL περιλαμβάνουν:

Ενοποίηση πύλης API: Εισαγωγή στη Διαχείριση API Azure για προσθήκη ελέγχου ταυτότητας, περιορισμού ρυθμού και προσωρινής αποθήκευσης
Ρύθμιση περιβάλλοντος ανάπτυξης: Διαμορφώστε το IntelliSense στον κώδικα του Visual Studio για αυτόματη συμπλήρωση και επικύρωση
Έλεγχος έκδοσης: Δέσμευση στο Git ή σε άλλα συστήματα ελέγχου προέλευσης για την παρακολούθηση της εξέλιξης του σχήματος με την πάροδο του χρόνου
Ομαδική συνεργασία: Μοιραστείτε με εξωτερικούς συνεργάτες ή ομάδες ανάπτυξης που πρέπει να κατανοήσουν τη δομή του API σας
Δημιουργία κώδικα: Χρησιμοποιήστε το με γεννήτριες κώδικα GraphQL για να δημιουργήσετε πελάτες ασφαλείς για τύπο σε TypeScript, C#, Java ή άλλες γλώσσες
Τεκμηρίωση: Δημιουργήστε τεκμηρίωση αναφοράς API χρησιμοποιώντας εργαλεία όπως το GraphQL Voyager ή το GraphQL Markdown

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

Διαχείριση αλλαγών σχήματος

Τα σχήματα GraphQL μπορούν να εξελιχθούν με την πάροδο του χρόνου καθώς προσθέτετε νέους τύπους, πεδία ή δυνατότητες στο API σας. Όταν αλλάζει το σχήμα, τα αρχεία SDL που εξάγονται καθίστανται παλιά. Εξετάστε αυτές τις πρακτικές:

Επανεξαγωγή μετά τις αλλαγές: Κάντε λήψη ενός νέου αρχείου SDL κάθε φορά που τροποποιείτε το σχήμα API στο Fabric. Οι αλλαγές σχήματος περιλαμβάνουν την προσθήκη προελεύσεων δεδομένων, την τροποποίηση εκτεθειμένων τύπων ή την ενημέρωση ορισμών πεδίων.
Στοιχείο ελέγχου έκδοσης: Δεσμεύστε κάθε εξαγόμενο σχήμα στο σύστημα ελέγχου προέλευσης με περιγραφικά μηνύματα υποβολής. Αυτό δημιουργεί μια διαδρομή ελέγχου της εξέλιξης του σχήματος και επιτρέπει την επαναφορά, εάν χρειάζεται.
Επικοινωνία: Εάν εξωτερικές ομάδες ή εφαρμογές εξαρτώνται από το σχήμα σας, ενημερώστε τις για σημαντικές αλλαγές. Ενώ το GraphQL υποστηρίζει πρόσθετες αλλαγές χωρίς να σπάει τα υπάρχοντα ερωτήματα, η αφαίρεση ή η μετονομασία πεδίων μπορεί να επηρεάσει τους πελάτες.
Αυτοματοποίηση: Για αγωγούς CI/CD, εξετάστε το ενδεχόμενο αυτοματοποίησης των εξαγωγών σχήματος ως μέρος της διαδικασίας ανάπτυξης για να διασφαλίσετε ότι η τεκμηρίωση και τα εργαλεία παραμένουν συγχρονισμένα με το API σας.

Το άτομο που είναι υπεύθυνο για την τροποποίηση του σχήματος API (συνήθως ένας μηχανικός δεδομένων ή προγραμματιστής API) θα πρέπει να εξάγει και να εκδίδει το ενημερωμένο σχήμα για να διατηρήσει τη συνέπεια μεταξύ του API Fabric και των εξωτερικών συστημάτων που εξαρτώνται από αυτό.

Ανάδραση

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

Last updated on 2026-01-20