GQL-kyselyn ohjelmointirajapinnan viittaus

Note

Tämä ominaisuus on tällä hetkellä julkisessa esikatselussa. Tämä esikatselu tarjotaan ilman palvelutasosopimusta, eikä sitä suositella tuotantokuormituksiin. Tiettyjä ominaisuuksia ei ehkä tueta tai niiden ominaisuudet voivat olla rajoitettuja. Katso lisätietoja artikkelista Supplemental Terms of Use for Microsoft Azure Previews.

Suorita GQL-kyselyjä Microsoft Fabricin kaavion ominaisuuskaavioista RESTful HTTP -ohjelmointirajapinnan avulla. Tässä viitteessä kuvataan HTTP-sopimus: pyyntöjen ja vastausten muodot, todentaminen, JSON-tuloskoodaus ja virheenkäsittely.

Tärkeää

Tässä artikkelissa käytetään yksinomaan sosiaalisen verkoston esimerkkikaaviodatasettiä.

Yleiskatsaus

GQL-kyselyn ohjelmointirajapinta on yksittäinen päätepiste (RPC over HTTP), joka hyväksyy GQL-kyselyt JSON-hyötykuormiksi ja palauttaa jäsennettyjä, kirjoitettuja tuloksia. Ohjelmointirajapinta on tilaton ja käsittelee todentamisen ja tarjoaa kattavan virheraportoinnin.

Tärkeimmät ominaisuudet

Yksittäinen päätepiste : kaikki toiminnot käyttävät HTTP POST -toimintoa yhteen URL-osoitteeseen.
JSON-pohjainen – Pyyntöjen ja vastausten tiedot käyttävät JSON:ää ja monipuolista tyyppisten GQL-arvojen koodausta.
Tilaton – Ei istuntotilaa pyyntöjen välillä.
Tyyppi turvallinen - Vahva, GQL-yhteensopiva kirjoitus ja syrjityt liitot arvoedustuksen vuoksi.

Edellytykset

Tarvitset kaavion, joka sisältää tietoja, kuten solmuja ja reunoja (suhteita). Tarkastele kaavion pikaopasta mallikaavion luomiseksi ja lataamiseksi.
Ominaisuuskaavioiden ja GQL:n perusymmärryksen tulisi olla sinulle tuttuja, kuten suoritustulosten ja tulosten rakenne.
Sinun on asennettava ja määritettävä Azure CLI -työkalu az, jotta voit kirjautua sisään organisaatioosi. Tämän artikkelin komentoriviesimerkeistä oletetaan, että käytät POSIX-yhteensopivaa komentoriviliittymää, kuten bashia.

Todennus

GQL-kyselyn ohjelmointirajapinta edellyttää todentamista haltijatunnusten kautta.

Sisällytä käyttöoikeustietue jokaisen pyynnön Valtuutus-otsikkoon:

Authorization: Bearer <your-access-token>

Yleisesti ottaen voit hankkia haltijatunnuksia käyttämällä Microsoft Authentication Library (MSAL) tai muita Microsoft Entra kanssa yhteensopivia todennustyönkulkuja.

Haltijatunnukset saadaan yleensä kahden pääpolun kautta:

Käyttäjän delegoitu käyttöoikeus

Voit hankkia käyttäjän delegoimien palvelukutsujen haltijatunnukset komentoriviltä Azure CLI -työkalun kautta az.

Hanki käyttäjän delegoimien kutsujen haltijatunnus komentoriviltä seuraavasti:

Suorita az login
Sitten az account get-access-token --resource https://api.fabric.microsoft.com

Tämä käyttää Azure CLI -työkalua az.

Kun käytät -toimintoa az rest pyyntöjen suorittamiseen, haltijatunnukset hankitaan automaattisesti.

Sovelluksen käyttö

Voit hankkia Microsoft Entra rekisteröityjen sovellusten haltijatunnukset. Saat lisätietoja Fabric API -pikaoppaasta .

Ohjelmointirajapinnan päätepiste

Ohjelmointirajapinta käyttää yhtä päätepistettä, joka hyväksyy kaikki kyselytoiminnot:

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

Jos haluat saada {workspaceId} -sovelluksen työtilaasi, voit luetella kaikki käytettävissä olevat työtilat käyttämällä :az rest

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

Jos haluat saada -{graphId}kohteen, voit luetella työtilan kaikki käytettävissä olevat kaaviot käyttämällä :az rest

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

Lisäparametrien avulla voit rajata tarkemmin kyselyn tuloksia:

--query 'value[?displayName=='My Workspace']luetteloinnille vain kohteet, joilla on .displayNameMy Workspace
--query 'value[starts_with(?displayName='My')] jos haluat luetella vain kohteet, joiden displayName alussa on My.
--query '{query}' jos haluat luetella vain kohteet, jotka vastaavat annettua JMESPath -polkua {query}. Lisätietoja :n tuetuista syntakseista on {query}.
-o table taulukkotuloksen tuottamiseen.

Note

Lisätietoja kyselyjen suorittamisesta komentorivin komentoriviliittymästä on kohdassa Toz-rest-toiminnon käyttäminen tai kiharan käyttäminen -osio .

Pyyntöotsikot

Otsikko	Arvo	Pakollinen
`Content-Type`	`application/json`	Kyllä
`Accept`	`application/json`	Kyllä
`Authorization`	`Bearer <token>`	Kyllä

Pyynnön muoto

Kaikissa pyynnöissä käytetään HTTP POST -yhteyttä JSON-hyötykuorman kanssa.

Peruspyyntörakenne

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

Pyyntökentät

Field	Tyyppi	Pakollinen	Kuvaus
`query`	merkkijono	Kyllä	Suoritettava GQL-kysely

Vastauksen muoto

Kaikissa onnistuneiden pyyntöjen vastauksissa käytetään HTTP 200 -tilaa ja JSON-tiedot sisältävät suorituksen tilan ja tulokset.

Vastausrakenne

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

Tilaobjekti

Jokainen vastaus sisältää tilaobjektin, joka sisältää suoritustietoja:

Field	Tyyppi	Kuvaus
`code`	merkkijono	kuusimerkkinen tilakoodi (000000 = onnistui)
`description`	merkkijono	Ihmisen luettavissa oleva tilasanoma
`diagnostics`	objekti	Yksityiskohtaiset diagnostiikkatietueet
`cause`	objekti	Valinnainen pohjana oleva syyn tilaobjekti

Tilakoodit

Tilakoodit noudattavat hierarkkista mallia:

00xxxx - Täydellinen onnistuminen
01xxxx - Onnistuminen ja varoitukset
02xxxx – Onnistuminen ilman tietoja
03xxxx - Onnistuminen ja tiedot
04xxxx ja korkeammat – virheet ja poikkeusehdot

Katso lisätietoja GQL-tilakoodien viittauksesta.

Diagnostiikkatietueet

Diagnostiset tietueet voivat sisältää muita avain-arvo-pareja, jotka kertovat tarkemmin tilaobjektista. Alaviivalla (_) alkavat avaimet ovat kaaviokohtaisia. GQL-standardi määrää kaikki muut avaimet.

Note

Kaaviokohtaisten avainten diagnostiikkatietueen arvot ovat JSON-koodattuja GQL-arvoja. Katso Arvotyypit ja koodaus.

Aiheuttaa

Tilaobjektit sisältävät valinnaisen cause kentän, kun pohjana oleva syy tiedetään.

Muut tilaobjektit

Jotkin tulokset voivat ilmoittaa muista tilaobjekteista luettelona (valinnainen) additionalStatuses kentässä.

Jos näin on, ensisijainen tilaobjekti määritetään aina olemaan kaikkein kriittisin tilaobjekti (kuten poikkeusehto), kuten GQL-standardin määrittämä tila.

Tulostyypit

Tuloksissa käytetään syrjimää liittomallia kind kentän kanssa:

Taulukon tulokset

Kyselyt, jotka palauttavat taulukkomuotoisia tietoja:

{
  "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
    }
  ]
}

Jätetty pois tulokset

Toiminnoille, jotka eivät palauta tietoja (esimerkiksi luettelo- ja/tai tietopäivitykset):

{
  "kind": "NOTHING"
}

Arvotyypit ja koodaus

Ohjelmointirajapinta käyttää monityyppistä järjestelmää edustamaan GQL-arvoja tarkan semantiikan avulla. GQL-arvojen JSON-muoto noudattaa syrjittyä union-muotoa.

Note

Taulukkomuotoisten tulosten JSON-muoto toteuttaa syrjityn yhdistämismallin erottamalla gqlType toisistaan ja value saavuttaakseen kompaktimman esityksen. Katso Taulukon sarjoituksen optimointi.

Arvorakenne

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

Primitiivityypit

GQL-tyyppi	Esimerkki:	Kuvaus
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Alkuperäinen JSON-totuusarvo
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8-merkkijono

Numeeriset tyypit

Kokonaislukutyypit

GQL-tyyppi	Alue	JSON-sarjoitus	Esimerkki:
`INT64`	-2³–2³-1	Luku tai merkkijono*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0–2-1	Luku tai merkkijono*	`{"gqlType": "UINT64", "value": 18467}`

JavaScriptin turvallisen alueen ulkopuolella suuret kokonaisluvut (-9 007 199 254 740 991 – 9 007 199 254 740 991) on sarjoitettu merkkijonoina:

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

Liukulukutyypit

GQL-tyyppi	Alue	JSON-sarjoitus	Esimerkki:
`FLOAT64`	IEEE 754 binary64	JSON-numero tai merkkijono	`{"gqlType": "FLOAT64", "value": 3.14}`

Liukulukuarvot tukevat IEEE 754 -erikoisarvoja:

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

Ajalliset tyypit

Tuetut ajalliset tyypit käyttävät ISO 8601 -merkkijonomuotoja:

GQL-tyyppi	Format	Esimerkki:
`ZONED DATETIME`	VVVV-KK-PPTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Kaavioelementtien viittaustyypit

GQL-tyyppi	Kuvaus	Esimerkki:
`NODE`	Kaaviosolmuviittaus	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Kaavion reunaviittaus	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Monimutkaiset tyypit

Monimutkaiset tyypit koostuvat muista GQL-arvoista.

Listat

Luettelot sisältävät tyhjäarvoja sisältäviä matriiseja, joissa on yhtenäiset elementtityypit:

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

Erikoisluettelotyypit:

LIST<ANY> - Yhdistelmätyypit (jokainen elementti sisältää täydelliset tiedot)
LIST<NULL> - Vain tyhjäarvot sallitaan
LIST<NOTHING> - Aina tyhjä matriisi

Polkuja

Polut on koodattu kaavioelementtien viitearvojen luetteloiksi.

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

Katso Taulukon sarjoituksen optimointi.

Taulukon sarjoittamisen optimointi

Taulukkotuloksissa arvon sarjoitus optimoidaan saraketyyppitietojen perusteella:

Tunnetut tyypit – vain raaka-arvo sarjoitetaan
KAIKKI sarakkeet – Koko arvon objekti, jonka tyyppi on syrjivä

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

Virheenkäsittely

Siirtovirheet

Verkko- ja HTTP-siirtovirheet aiheuttavat vakiomuotoiset HTTP-virheen tilakoodit (4xx, 5xx).

Sovellusvirheet

Sovellustason virheet palauttavat aina HTTP 200 -virheen, jonka tilaobjektissa on virhetiedot:

{
  "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": "/"
      }
    }
  }
}

Tilan tarkistus

Tarkista onnistumisen tarkistamalla tilakoodi:

Koodit, jotka alkavat tunnuksilla 00, 0102, 03 osoittavat onnistumisen (mahdollisilla varoituksilla)
Kaikki muut koodit ilmaisevat virheitä

Täydellinen esimerkki, jossa on az rest

Suorita kysely komennolla az rest , jotta haltijatunnuksia ei tarvitse hankkia manuaalisesti. Toimi seuraavasti:

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" 
}'

Täydellinen esimerkki kiharasta

Tämän osion esimerkissä käytetään työkalua curl , jonka avulla voidaan suorittaa HTTPS-pyyntöjä käyttöliittymästä.

Oletamme, että sinulla on kelvollinen käyttöoikeustietue tallennettuna liittymämuuttujaan, kuten:

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

Vihje

Katso todentamista käsittelevästä osiosta , miten voit hankkia kelvollisen haltijatunnuksen.

Suorita tällainen kysely:

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" 
  }'

Parhaat käytännöt

Noudata näitä parhaita käytäntöjä, kun käytät GQL-kyselyn ohjelmointirajapintaa.

Virheenkäsittely

Tarkista aina tilakoodit – Älä oleta onnistuvan HTTP 200 -yhteyden perusteella.
Jäsennä virhetiedot : käytä vianmäärityksen ja syyn ketjuja virheenkorjaukseen.

Security

HTTPS:n käyttäminen : älä koskaan lähetä todennustunnuksia salaamattomien yhteyksien kautta.
Kiertotunnukset : ota käyttöön asianmukainen tunnuksen päivitys ja sen vanhentuminen.
Vahvista syötteet : voit puhdistaa ja välttää oikein käyttäjän antamat kyselyparametrit, jotka on syötetty kyselyyn.

Arvoesitys

Käsittele suuria kokonaislukuarvoja – Kokonaisluvut koodataan merkkijonoina, jos niitä ei voi esittää JSON-numeroina suoraan.
Käsittele erityisiä liukulukuarvoja – kyselyistä palautetut liukulukuarvot voivat olla Infinity, -Infinitytai NaN (ei luku).
Käsittele tyhjäarvot – JSON-tyhjäarvo edustaa GQL-tyhjäarvoa.

Palaute

Onko tästä sivusta apua?

Last updated on 2026-03-12

Jaa

GQL-kyselyn ohjelmointirajapinnan viittaus

Yleiskatsaus

Tärkeimmät ominaisuudet

Edellytykset

Todennus

Käyttäjän delegoitu käyttöoikeus

Sovelluksen käyttö

Ohjelmointirajapinnan päätepiste

Pyyntöotsikot

Pyynnön muoto

Peruspyyntörakenne

Pyyntökentät

Vastauksen muoto

Vastausrakenne

Tilaobjekti

Tilakoodit

Diagnostiikkatietueet

Aiheuttaa

Muut tilaobjektit

Tulostyypit

Taulukon tulokset

Jätetty pois tulokset

Arvotyypit ja koodaus

Arvorakenne

Primitiivityypit

Numeeriset tyypit

Kokonaislukutyypit

Liukulukutyypit

Ajalliset tyypit

Kaavioelementtien viittaustyypit

Monimutkaiset tyypit

Listat

Polkuja

Taulukon sarjoittamisen optimointi

Virheenkäsittely

Siirtovirheet

Sovellusvirheet

Tilan tarkistus

Täydellinen esimerkki, jossa on az rest

Täydellinen esimerkki kiharasta

Parhaat käytännöt

Virheenkäsittely

Security

Arvoesitys

Aiheeseen liittyvä sisältö

Palaute

Lisäresursseja