Vianmääritys Microsoft Fabric REST API:t

Esittely

Tämä artikkeli auttaa sinua ymmärtämään ja vianmäärittämään yleisiä virheitä, joita Microsoft Fabric REST API:t palauttavat. Se selittää palvelun käyttämän standardivirhemuodon ja antaa ohjeita yleisimmin esiintyvien HTTP-tilakoodien ratkaisemiseen.

Ymmärrä Microsoft Fabricin virhevastaukset

Kun Microsoft Fabric REST API:n pyynnön käsittelyssä tapahtuu virhe, palvelu palauttaa vastausrunkoon standardiobjektin ErrorResponse .

Vianetsinnässä tallenna ja kirjaa aina , requestIdsillä se yksilöi pyynnön ja on tarpeen Microsoftin tukeen ottamisessa. Pyyntötunnus on saatavilla sekä vastausrungossa että vastausotsikoissa.

Tärkeää

  • errorCode arvot ovat stabiileja ja sopimuspohjaisia.
  • Ihmisen luettava message teksti voi muuttua ajan myötä, eikä sitä tulisi jäsentää ohjelmallisesti.

ErrorResponse-skeema

Nimi Tyyppi Kuvaus
errorCode string Vakaa tunniste virheehdolle. Käytä tätä arvoa virheenkäsittelylogiikan toteuttamisessa.
message string Ihmisen luettava kuvaus virheestä.
moreDetails ErrorResponseDetails[] Valinnainen lista lisävirhetiedoista.
relatedResource ErrorRelatedResource Tietoa virheeseen liittyvästä resurssista, jos sovellettavissa.
requestId string Epäonnistuneen pyynnön yksilöllinen tunniste. Sisällytä tämä arvo ottaessasi yhteyttä Microsoftin tukeen.

ErrorResponseDetails-skeema

Tarjoaa lisäkontekstia monimutkaisille virhetilanteille.

Nimi Tyyppi Kuvaus
errorCode string Vakaa tunniste, joka kuvaa tarkkaa virheyksityiskohtaa.
message string Ihmisen luettava selitys virheen yksityiskohdalle.
relatedResource ErrorRelatedResource Resurssi, joka liittyy tähän virheyksityiskohtaan.

ErrorRelatedResource -skeema

Tunnistaa virheeseen liittyvän resurssin.

Nimi Tyyppi Kuvaus
resourceId string Virheeseen osallistuneen resurssin tunniste.
resourceType string Resurssin tyyppi (esimerkiksi työtila, esine tai kapasiteetti).

Yleiset HTTP-virhetilanteet

Seuraavissa osioissa kuvataan Microsoft Fabric REST API:n palauttamat yleiset HTTP-tilakoodit, mukaan lukien tyypilliset juurisyät ja suositellut resoluutiot.

API palauttaa lomakkeen 401 – Luvaton

401-vastaus osoittaa, että pyyntö epäonnistui todennuksessa tai käyttötunnisteen validoinnissa.

Yleisiä juurisyitä

Virhekoodi Kuvaus Ratkaisu
TokenExpired Pääsytunnus on vanhentunut. Hanki uusi pääsytunnus ja yritä pyyntöä uudelleen.
InsufficientScopes Pääsytunnus ei sisällä vaadittuja scope-alueita. Päivitä sovellus pyytämään vaaditut laajuudet, kuten API-määrittelyssä on dokumentoitu, tai päivitä Microsoft Entra -sovelluksen rekisteröinti.

API palauttaa 403 – Kielletty

403-vastaus osoittaa, että soittaja on todennettu, mutta hänellä ei ole riittäviä oikeuksia suorittaa pyydettyä operaatiota kohderesurssilla.

Yleisiä juurisyitä

Virhekoodi Kuvaus Ratkaisu
InsufficientPrivileges Soittajalla ei ole tarvittavia oikeuksia resurssiin pääsyyn. Pyydä työtilan tai resurssien ylläpitäjää myöntämään riittävät oikeudet kutsuvalle käyttäjälle tai palvelupäämiehelle.

API palauttaa 404 – Ei löytynyt

404-vastaus tarkoittaa, että pyydetty tai viitattu resurssi ei ole olemassa tai ei ole soittajan käytettävissä.

Muistio

Yksittäiset API:t voivat määritellä lisäominaisuuksia, API-kohtaisia virhekoodeja. Katso aina API-määrittelyä saadaksesi valtuutetut tiedot.

Yleisiä juurisyitä

Virhekoodi Kuvaus Ratkaisu
WorkspaceNotFound Määriteltyä työtilaa ei löytynyt. Varmista, että oikea työtilan objektitunnus on annettu.
EntityNotFound Pyydettyä resurssia ei löytynyt. Varmista, että oikea resurssitunnus on annettu. Puuttuva entiteetti tunnistetaan relatedResource virhevastauksen kentässä.

API palauttaa 429 – Liian monta pyyntöä

429-vastaus kertoo, että pyyntöä rajoitettiin. Microsoft Fabric palauttaa 429-tilakoodin kahdesta eri syystä, jotka kumpikin tunnistetaan errorCode eri vastausrunkossa.

Yleisiä juurisyitä

Virhekoodi Kuvaus Ratkaisu
RequestBlocked Pyyntöjen määrä ylitti palvelun rajoitusrajat. Odota otsikossa määriteltyä Retry-After kestoa ennen kuin yrität uudelleen. Katso hakemuksestasi Käsittele nopeusrajoitusta.
CapacityLimitExceeded Kapasiteetissa kulutettu laskenta (kapasiteettiyksiköt) ylitti ostetun Fabric SKU:n rajat. Yritä pyyntö uudelleen myöhemmin. Katso Kahvan kapasiteetin rajoittaminen.

Nopeusrajoitus (RequestBlocked)

Virhe RequestBlocked tarkoittaa, että pyyntönopeus ylitti palvelun rajoitusrajat.

  • Rajoitus on voimassa soittajan identiteettiä kohtaan.
  • Nopeusrajat arvioidaan tyypillisesti yhden minuutin jaksoissa.

Uusintayrityksen ajoitustiedot

Kun nopeusrajoitus tapahtuu, uusintayritystiedot annetaan kahdessa paikassa:

  • Vastekappale (message)
    Esimerkki:
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After HTTP-vastausotsikko
    Määrittelee, kuinka monta sekuntia asiakkaan täytyy odottaa ennen uudelleenyrittämistä.

Suosi aina otsikkoa Retry-After , kun toteutat uudelleenyrittämislogiikkaa.

Käsittele nopeusrajoituksia hakemuksessasi

Sovellusten tulisi:

  • Tunnista HTTP 429 -vastaukset.
  • Jäsentele ja kunnioita otsikkoa Retry-After .
  • Sovella rajoitettua uudelleenyrittämispolitiikkaa, kuten eksponentiaalista peruutusta jitterillä suurissa skenaarioissa.
  • Vältä loputtomia uusintasilmukoita.

Vähennä nopeusrajoituksen todennäköisyyttä

  • Käytä erä- ja erätoimintoja , kun mahdollista.
  • Suosi listarajapintoja toistuvien yksittäisresurssipyyntöjen sijaan.
  • Välimuisti usein käytettyjä tietoja, erityisesti harvoin muuttuvaa metatietoa.
  • Vältä liikennepiikkejä jakamalla pyynnöt tasaisesti ajan kuluessa.

Kapasiteettiraja ylitetty (CapacityLimitExceeded)

Virhe CapacityLimitExceeded tarkoittaa, että kapasiteetillasi kulutettu laskenta (kapasiteettiyksiköt) ylittivät ostetun Fabric SKU:n rajat. Toisin kuin nopeusrajoituksessa, tämä rajoitus ei johdu siitä, kuinka monta API-kutsua tietty soittaja tekee; se heijastaa kapasiteetin kaikkien työkuormien kokonaislaskentaa.

Esimerkki vastauselimestä:

"Your organization's Fabric compute capacity has exceeded its limits. Try again later."

Kahvan kapasiteetin rajoitus

Koska tämä rajoitus riippuu kapasiteetin kokonaislaskentamäärästä, ei yksittäisestä pyyntönopeudestasi, otsikko Retry-After ei ole sovellettavissa, eikä välitön uudelleenyrittäminen todennäköisesti onnistu ennen kuin kapasiteetin laskenta palaa rajojensa sisälle. Sovellusten tulisi:

  • Kokeile pyyntöä myöhemmin uudelleen rajoitetulla uudelleenyrittämiskäytännöllä, jossa on eksponentiaalinen peruutus.
  • Jos virhe jatkuu, harkitse Fabric-kapasiteetin skaalaamista tai laajentamista.

Lisätietoja kapasiteettiyksiköistä, SKU:ista ja siitä, miten Fabric-kapasiteetti kulutetaan, löydät kohdasta Suunnittele kapasiteettikoko.

Summary

Luotettavien integraatioiden rakentaminen Microsoft Fabricin REST API:en kanssa vaatii vahvaa virheenkäsittelyä ja tehokkaita pyyntökuvioita. Ymmärtämällä virhevasteita, kunnioittamalla rajoitussignaaleja ja optimoimalla pyyntökuvioita voit rakentaa kestäviä sovelluksia.

Liittyvä sisältö

Lisäkysymyksiä tai yhteisön ohjeita varten katso Microsoft Fabric Community

  • Last updated on