GQL-kyselyn ohjelmointirajapinnan viittaus

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-kyselyrajapinta paljastaa REST-päätepisteen, joka hyväksyy GQL-kyselyt JSON-hyötykuormina ja palauttaa jäsenneltyjä, tyypitettyjä tuloksia. Se tukee jatkokyselyä kyselyille, jotka eivät valmistu alkuperäisen pyynnön aikana.

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.
Jatkokysely – Pitkäkestoiset kyselyt voivat jatkua useiden HTTP-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?beta=true

Kyselyrajapinta on betavaiheessa eikä sitä suositella tuotantokäyttöön. Aseta vaadittu beta kyselyparametri .true Vanhempi preview=true parametri on edelleen tuettu taaksepäin yhteensopivuuden vuoksi, mutta sitä käytetään beta=true uusissa integraatioissa.

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

Voit käyttää Azure CLI:n tulostusasetuksia suodattaaksesi tai muotoillaksesi vastauksia näistä listapyynnöistä. Nämä asetukset suoritetaan Azure CLI -asiakasohjelmassa; ne eivät ole Query API -parametreja:

--query "value[?displayName=='My Workspace']"listaa vain kohteet, joissa on .displayNameMy Workspace
--query "value[?starts_with(displayName, 'My')]" Listaa vain alkiot, joiden displayName alussa on My.
--query "{query}" listaa vain tuotteet, jotka vastaavat annettua JMESPathia {query}. Katso Query Azure CLI -komentotulokset tuetusta syntaksista.
-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 .

Kyselyparametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
`beta`	totuusarvo	Kyllä	Asetettu `true` käyttämään beta-kyselyrajapintaa.
`continuationToken`	merkkijono	Ei	Token siitä `result.nextPage` , kun kysely on vielä käynnissä. Lähetä sama kyselyteksti, kun käytät tokenia.

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": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Tilaobjekti

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

Field	Tyyppi	Kuvaus
`code`	merkkijono	Viiden merkin julkinen API-tilakoodi.
`description`	merkkijono	Ihmisen luettava tilakuvaus.
`diagnostics`	objekti	Yksityiskohtainen diagnostiikka, mukaan lukien kanoninen kyselymoottorin GQLSTATUS kun saatavilla.
`cause`	objekti	Valinnainen taustalla oleva syytila-objekti.

Tilakoodit

Ensisijainen status.code käyttää näitä julkisia API-luokkia:

00000 - Onnistunut suoritus vähintään yhdellä rivillä.
00001 - Onnistunut suoritus ilman tulosta. Varattu tulevaa DDL- ja DML-tukea varten.
01000 - Varoitus- tai informaatioehto.
02000 - Riviä tuottavasta kyselystä ei tällä hetkellä ole käytettävissä.
42000 - Syntaksi, käyttöoikeussääntö tai muu käyttäjän korjattava kyselyvirhe.
50000 - Järjestelmä- tai luokittelematon virhe.

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

Diagnostiikka _graphaneGqlStatus sisältää kyselymoottorin raportoiman kanonisen viiden merkin GQLSTATUSin. Jokainen alaviivaetuliitteellä varustettu diagnostiikkajäsen sisältää joko null tai JSON-koodatun GQL-arvon. Esimerkiksi käyttää _graphaneGqlStatusSTRING, kun taas virheluokitteludiagnostiikka käyttää BOOL. Katso Arvotyypit ja koodaus.

Aiheuttaa

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

Muut tilaobjektit

Jotkut tulokset voivat raportoida muita tilaobjekteja listana valinnaisessa additionalStatuses kentässä.

Ensisijainen tila on kriittisin kirjattu tila. Jokaisella lisätilalla ja sisäkkäisellä syyllä on oma julkinen API-koodinsa ja kanoninen GQLSTATUS-diagnostiikka.

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": "INT64",
      "jsonType": "number|string"
    }
  ],
  "isOrdered": false,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

Pitkäkestoiset kyselyt

Jos kysely ei valmistu nykyisen HTTP-pyynnön aikana, API palauttaa HTTP 200:n julkisella tilakoodilla 02000, tyhjällä taululla ja nextPage tokenilla:

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

Kysely suorittamiseksi lähettämällä sama pyyntörunko ja lisäämällä token URL-osoitteeseen:

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

Käsittele nextPage sitä läpinäkymättömänä arvona. Koodaa se prosenttiosuudella täsmälleen kerran RFC 3986:n mukaisesti ennen kuin käytät continuationToken sitä kyselyparametrin arvona. Älä pura, tutki tai muokkaa tokenia.

Jatka, kunnes vastaus ei enää sisällä nextPage. Kyselyn suoritus voi jatkua jopa 20 minuuttia alkuperäisestä pyynnöstä. Jos se ylittää tuon kokonaiskestoa, API palauttaa HTTP 408:n virhekoodilla QueryTimeout.

Lyhennetyt tulokset

Graafi katkaisee kyselyvastauksen, kun sen sisäinen binääriesitys ylittää 64 MB. API palauttaa rivit, jotka sopivat, ja lisää tilan .additionalStatuses Lisätila käyttää julkista koodia 01000 ja säilyttää kanonisen GQLSTATUKSEN 01M11 ._graphaneGqlStatus

Katkaisu ei tuota nextPage tokenia pois jätetyille riveille. Rajaa kysely suodattimilla, tietyillä projektioilla tai LIMIT, ja suorita se uudelleen.

Jätetty pois tulokset

Vasteskeema voi edustaa operaatiota, jonka lause ei koskaan tuota rivejä, riippumatta datasta tai arviointituloksesta. Tämä tulos käyttää tilakoodia 00001:

{
  "kind": "NOTHING"
}

Tämä pois jätetty tulos eroaa taulukosta, jossa ei ole rivejä. Tyhjä taulu on tulos, kun arvioidaan riviä tuottava kysely, jolla ei tällä hetkellä ole palautettavia rivejä.

Graph varaa tämän tulosmuodon ja tilakoodin tulevalle datamäärittelykielelle (DDL) ja datan käsittelykielelle (DML). Nykyiset kyselylauseet palauttavat aina taulukon tulokset.

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ä

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

Virheenkäsittely

Siirtovirheet

HTTP-tila ja GQL-tila kuvaavat vastauksen eri tasoja:

HTTP-tila	Merkitys
200	API käsitteli pyynnön. Tarkista `status.code` , koska tulos voi edustaa onnistumista, rivejä puuttumista, vielä keskeneräistä kyselyä tai käyttäjän korjattavaa kyselyvirhettä.
408	Kyselyn suoritus ylitti 20 minuutin kokonaisaikalisän. Virhekoodi on `QueryTimeout`.
429	Palveluhinnan raja ylitettiin. Odota otsikon kestoa `Retry-After` ennen kuin yrität uudelleen.
499	Soittaja peruutti pyynnön. Virhekoodi on `ClientCancelled`.
Muut 4xx tai 5xx	Pyyntö tai palvelu epäonnistui ennen kuin GQL-suoritustulos palautettiin. Tarkista HTTP-virhevastaus.

Sovellusvirheet

Sovellustason virhe voi palauttaa HTTP 200:n, jossa virhetiedot ovat tilaobjektissa. Esimerkiksi nollalla jakaminen käyttää julkista API-koodia 42000 ja säilyttää kanonisen GQLSTATUKSEN 22012 diagnostiikkatietueessa:

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

Tilan tarkistus

Laajemman lopputuloksen määrittämiseksi tarkista yleisö status.code. Käytä _graphaneGqlStatus sitä, kun sovelluksesi täytyy erottaa tietty kyselymoottorin ehto, kuten numeerinen ylivuoto (22003) ja nollan jakaminen (22012).

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

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

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.
Validoi syötteet – Validoi ja poista oikein kaikki käyttäjän antamat arvot, jotka sovelluksesi lisää kyselytekstiin.

Arvoesitys

Käsittele suuria kokonaislukuarvoja – Kokonaisluvut koodataan merkkijonoina, jos niitä ei voi esittää JSON-numeroina suoraan.
Käsittele erityisiä liukulukuarvoja – API sarjoittaa positiivisen äärettömyyden, negatiivisen äärettömyyden, ei-luvun ja negatiivisen nollan muodossa "Inf", "-Inf", "NaN", ja "-0".
Käsittele tyhjäarvot – JSON-tyhjäarvo edustaa GQL-tyhjäarvoa.

Palaute

Onko tästä sivusta apua?

Viimeksi päivitetty 2026-09-29

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

Kyselyparametrit

Pyyntöotsikot

Pyynnön muoto

Peruspyyntörakenne

Pyyntökentät

Vastauksen muoto

Vastausrakenne

Tilaobjekti

Tilakoodit

Diagnostiikkatietueet

Aiheuttaa

Muut tilaobjektit

Tulostyypit

Taulukon tulokset

Pitkäkestoiset kyselyt

Lyhennetyt 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