Spør Microsoft Graph ved hjelp av REST

  • 3 minutter

Microsoft Graph er en RESTful web-API som gir deg tilgang til Microsoft Cloud Service-ressurser. Når du har registrert appen og fått godkjenningstokener for en bruker eller tjeneste, kan du sende forespørsler til Microsoft Graph-API-en.

Microsoft Graph-API-en definerer de fleste ressurser, metoder og opplistinger i OData-navneområdet, microsoft.graph, i Microsoft Graph-metadata. Noen API-sett er definert i undernavneområdene, for eksempel kall registrerer API-en som definerer ressurser som callRecord i microsoft.graph.callRecords.

Med mindre det er angitt eksplisitt i det tilsvarende emnet, er anta at typer, metoder og opplistinger er en del av microsoft.graph navneområdet.

Kall en REST-API-metode

Hvis du vil lese fra eller skrive til en ressurs, for eksempel en bruker eller en e-postmelding, kan du konstruere en forespørsel som ser ut som følgende eksempel:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Komponentene i en forespørsel inkluderer:

  • {HTTP method} – HTTP-metoden som brukes på forespørselen til Microsoft Graph.
  • {version} – Versjonen av Microsoft Graph-API-en som programmet bruker.
  • {resource} – ressursen i Microsoft Graph som du refererer til.
  • {query-parameters} – Valgfrie OData-spørringsalternativer eller REST-metodeparametere som tilpasser svaret.

Når du har gjort en forespørsel, returneres et svar som inkluderer:

  • Statuskode – en HTTP-statuskode som angir vellykket eller mislykket.
  • Svarmelding – dataene du ba om, eller resultatet av operasjonen. Svarmeldingen kan være tom for enkelte operasjoner.
  • nextLink – Hvis forespørselen returnerer mange data, må du bla gjennom den ved hjelp av nettadressen som returneres i @odata.nextLink.

HTTP-metoder

Microsoft Graph bruker HTTP-metoden på forespørselen din til å finne ut hva forespørselen din gjør. API-en støtter følgende metoder.

Metode Beskrivelse
FÅ Les data fra en ressurs.
POST Opprett en ny ressurs, eller utfør en handling.
PATCH Oppdater en ressurs med nye verdier.
PUTTE Erstatt en ressurs med en ny ressurs.
SLETTE Fjern en ressurs.
  • For CRUD-metodene GET og DELETEkreves det ingen forespørselstekst.
  • Metodene POST, PATCHog PUT krever en forespørselstekst angitt i JSON-format som inneholder tilleggsinformasjon. For eksempel verdiene for egenskapene til ressursen.

Versjon

Microsoft Graph støtter for øyeblikket to versjoner: v1.0 og beta.

  • v1.0 inkluderer generelt tilgjengelige API-er. Bruk v1.0-versjonen for alle produksjonsapper.
  • beta inkluderer API-er som for øyeblikket er i forhåndsversjon. Fordi vi kan introdusere bruddendringer i beta-API-ene våre, anbefaler vi at du bare bruker betaversjonen til å teste apper som er under utvikling. ikke bruk beta-API-er i produksjonsappene dine.

Ressurs

En ressurs kan være en enhet eller kompleks type, vanligvis definert med egenskaper. Enheter skiller seg fra komplekse typer ved alltid å inkludere en -ID- egenskap.

URL-adressen inneholder ressursen du samhandler med i forespørselen, for eksempel me, bruker, gruppe, driveog nettsted. Ressurser på øverste nivå inkluderer ofte også relasjoner, som du kan bruke til å få tilgang til andre ressurser, for eksempel me/messages eller me/drive. Du kan også samhandle med ressurser ved hjelp av metoder; Hvis du for eksempel vil sende en e-postmelding, kan du bruke me/sendMail.

Hver ressurs kan kreve forskjellige tillatelser for å få tilgang til den. Du trenger ofte et høyere tillatelsesnivå for å opprette eller oppdatere en ressurs enn å lese den. Hvis du vil ha mer informasjon om nødvendige tillatelser, kan du se emnet for metodereferanse.

Spørringsparametere

Spørringsparametere kan være alternativer for OData-systemspørring eller andre strenger som en metode godtar for å tilpasse svaret.

Du kan bruke valgfrie alternativer for OData-systemspørring til å inkludere flere eller færre egenskaper enn standardsvaret. Du kan filtrere svaret for elementer som samsvarer med en egendefinert spørring, eller angi en annen parameter for en metode.

Hvis du for eksempel legger til følgende filter parameter, begrenses meldingene som returneres med emailAddress-egenskapen jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Andre ressurser

Nedenfor finner du koblinger til noen verktøy du kan bruke til å bygge og teste forespørsler ved hjelp av Microsoft Graph API-er.