Utilizati API-ul Microsoft Graph – Microsoft Graph

• 02.06.2021
• 5 minute de citit

• • J

  • A

  • F

  • D

  • r

In acest articol

Microsoft Graph este un API web RESTful care va permite sa accesati resursele serviciului Microsoft Cloud. Dupa ce va inregistrati aplicatia si obtineti jetoane de autentificare pentru un utilizator sau serviciu, puteti face cereri catre API-ul Microsoft Graph.

Important: Modul in care politicile de acces conditionat se aplica Microsoft Graph se schimba. Aplicatiile trebuie actualizate pentru a gestiona scenarii in care sunt configurate politicile de acces conditionat. Pentru mai multe informatii si indrumari, consultati Orientari pentru dezvoltatori pentru acces conditionat Azure Active Directory.

Spatiu de nume OData

API-ul Microsoft Graph defineste majoritatea resurselor, metodelor si enumerarilor sale in spatiul de nume OData, microsoft.graph, in metadatele Microsoft Graph. Un numar mic de seturi de API sunt definite in sub-spatiile lor de nume, cum ar fi API-ul de inregistrari de apel care defineste resurse precum callRecord in microsoft.graph.callRecords.

Daca nu este specificat in mod explicit in subiectul corespunzator, presupunem ca tipurile, metodele si enumerarile fac parte din spatiul de nume microsoft.graph.

Apelati o metoda API REST

Pentru a citi sau a scrie pe o resursa, cum ar fi un utilizator sau un mesaj de e-mail, construiti o cerere care arata ca urmatoarea:

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

Componentele unei cereri includ:

• {Metoda HTTP} – Metoda HTTP utilizata la solicitarea catre Microsoft Graph.
• {version} – Versiunea Microsoft Graph API pe care o foloseste aplicatia dvs.
• {resource} – Resursa din Microsoft Graph la care faceti referire.
• {query-parameters} – Optiuni optionale de interogare OData sau parametri ai metodei REST care personalizeaza raspunsul.

Dupa ce faceti o solicitare, se returneaza un raspuns care include:

• Cod de stare – Un cod de stare HTTP care indica succesul sau esecul. Pentru detalii despre codurile de eroare HTTP, consultati Erori.
• Mesaj de raspuns – datele pe care le-ati solicitat sau rezultatul operatiei. Mesajul de raspuns poate fi gol pentru unele operatii.
• nextLink – Daca solicitarea dvs. returneaza o multime de date, trebuie sa o parcurgeti utilizand adresa URL returnata in @ odata.nextLink. Pentru detalii, consultati Paginarea.

Metode HTTP

Microsoft Graph utilizeaza metoda HTTP la cererea dvs. pentru a determina ce face cererea dvs. API accepta urmatoarele metode.

Metoda Descriere GET Cititi date dintr-o resursa. POST Creati o resursa noua sau efectuati o actiune. PATCH Actualizati o resursa cu valori noi. PUT Inlocuiti o resursa cu una noua. STERGERE Eliminati o resursa.

• Pentru metodele CRUD GET si DELETE, nu este necesar niciun organism de solicitare.
• Metodele POST, PATCH si PUT necesita un corp de solicitare, de obicei specificat in format JSON, care contine informatii suplimentare, cum ar fi valorile pentru proprietatile resursei.

Versiune

Microsoft Graph accepta in prezent doua versiuni: v1.0 si beta.

• v1.0 include API-uri disponibile in general. Utilizati versiunea v1.0 pentru toate aplicatiile de productie.
• beta include API-uri care sunt in prezent in previzualizare. Deoarece s-ar putea sa introducem modificari esentiale API-urilor noastre beta, va recomandam sa utilizati versiunea beta numai pentru a testa aplicatiile aflate in curs de dezvoltare; nu utilizati API-uri beta in aplicatiile dvs. de productie.

Cautam intotdeauna feedback despre API-urile noastre beta. Pentru a oferi feedback sau pentru a solicita caracteristici, consultati forumul nostru de idei pentru platforma pentru dezvoltatori Microsoft 365.

Pentru mai multe informatii despre versiunile API, consultati Versiuni si asistenta.

Resursa

O resursa poate fi o entitate sau un tip complex, definit in mod obisnuit cu proprietati. Entitatile difera de tipurile complexe prin includerea intotdeauna a unei proprietati id .

Adresa URL va include resursa cu care interactionati in cerere, cum ar fi eu, utilizatorul , grupul , unitatea si site-ul . Adesea, resursele de nivel superior includ si relatii , pe care le puteti utiliza pentru a accesa resurse suplimentare, cum ar fi eu / mesaje sau eu / unitate. De asemenea, puteti interactiona cu resursele folosind metode ; de exemplu, pentru a trimite un e-mail, utilizati mine / sendMail. Pentru mai multe informatii, consultati Accesarea datelor si metodelor navigand in Microsoft Graph.

Fiecare resursa poate necesita permisiuni diferite pentru a o accesa. Veti avea adesea nevoie de un nivel mai mare de permisiuni pentru a crea sau actualiza o resursa decat sa o cititi. Pentru detalii despre permisiunile necesare, consultati subiectul referintei metodei.

Pentru detalii despre permisiuni, consultati Referinta permisiunilor.

Parametrii interogarii

Parametrii de interogare pot fi optiuni de interogare a sistemului OData sau alte siruri pe care o metoda le accepta pentru a-si personaliza raspunsul.

Puteti utiliza optiunile de interogare optionale ale sistemului OData pentru a include mai multe sau mai putine proprietati decat raspunsul implicit, filtra raspunsul pentru elementele care se potrivesc cu o interogare personalizata sau furniza parametri suplimentari pentru o metoda.

De exemplu, adaugarea urmatorului parametru de filtrare restrictioneaza mesajele returnate numai celor cu proprietatea emailAddress a [email protected].

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq ‘[email protected]’

Pentru mai multe informatii despre optiunile de interogare OData, consultati Utilizarea parametrilor de interogare pentru a personaliza raspunsurile.

In afara de optiunile de interogare OData, unele metode necesita valori ale parametrilor specificate ca parte a adresei URL a interogarii. De exemplu, puteti obtine o colectie de evenimente care au avut loc intr-o perioada de timp in calendarul unui utilizator , interogand relatia calendarView a unui utilizator si specificand valorile perioadei startDateTime si endDateTime ca parametri de interogare:

Obtineti https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Instrumente pentru interactiunea cu Microsoft Graph

Graph Explorer

Graph Explorer este un instrument bazat pe web pe care il puteti utiliza pentru a crea si testa cereri utilizand API-urile Microsoft Graph. Puteti accesa Graph Explorer la: https://developer.microsoft.com/graph/graph-explorer.

Puteti accesa datele demo fara a va conecta sau va puteti conecta la un chirias propriu. Utilizati pasii urmatori pentru a crea solicitarea:

1. Selectati metoda HTTP.
2. Selectati versiunea API pe care doriti sa o utilizati.
3. Tastati interogarea in caseta de text a cererii.
4. Selectati Executare interogare .

Urmatorul exemplu arata o solicitare care returneaza informatii despre utilizatori in chiriasul demonstrativ:

Exemple de interogari sunt furnizate in Graph Explorer pentru a va permite sa rulati mai rapid solicitari comune. Pentru a vedea mostrele disponibile, selectati Afisati mai multe mostre . Selectati Activat pentru setul de esantioane pe care doriti sa le vedeti, iar dupa inchiderea ferestrei de selectie, ar trebui sa vedeti o lista de cereri predefinite.

Un cod de stare si un mesaj sunt afisate dupa trimiterea unei cereri si raspunsul este afisat in fila Previzualizare raspuns .

Postas

Postman este un instrument pe care il puteti utiliza pentru a crea si testa cereri folosind API-urile Microsoft Graph. Puteti descarca Postman de la: https://www.getpostman.com/. Pentru a interactiona cu Microsoft Graph in Postman, utilizati colectia Microsoft Graph.

Pentru mai multe informatii, consultati Utilizarea postasului cu API-ul Microsoft Graph.

Pasii urmatori

Sunteti gata sa incepeti si sa rulati cu Microsoft Graph. Incercati Startul rapid sau incepeti sa utilizati unul dintre SDK-urile si exemplele de cod.