Primii pași sunt foarte simpli: creați un depozit și inițializați o bijuterie simplă în el. O nouă bijuterie poate fi creată cu comanda bundle gem gem_name și un depozit poate fi creat pe Github. Iată-l, apropo: https://github.com/Fodoj/groovehq.
În primul rând, voi adăuga posibilitatea de a autentifica cererile la API-ul GrooveHQ, apoi voi scrie un minim codul necesar pentru a obține o listă cu toate biletele. Din fericire, documentația pentru API-ul acestui serviciu este detaliată și de înțeles, așa că nu va fi dificil să faceți o solicitare GET.
Client minim
Voi începe prin a scrie o mică clasă GrooveHQ :: Client care va fi responsabilă pentru efectuarea solicitărilor API. Constructorul acestei clase va lua jeton de acces.
# ./lib/groovehq/client.rb modul GrooveHQ class Client def initialize (access_token = nil) @access_token = access_token || ENV [„GROOVEHQ_ACCESS_TOKEN”] sfârșit sfârșit sfârșit
Cum se accesează API-ul
Acum trebuie să ne dăm seama cum să accesăm API-ul. Până în acest moment, nu am folosit niciodată bijuteria httparty pentru a face cereri. Experiența mea se limitează la bibliotecile RestClient și Faraday. Nu cred că există o mare diferenta ce bibliotecă să folosesc, dar pentru a face procesul mai interesant voi alege httparty. Mai mult, are o mulțime de stele pe GitHub :)
De fapt, îl urăsc pe Faraday.
Adaug următoarea linie la groovehq.gemspec:
# ./groovehq.gemspec # ... spec. add_dependency „httparty” # ...
și rulați instalarea pachetului. Rămâne doar să conectați httparty în interior. / Lib / groovehq.rb:
Efectuarea primei solicitări API
Pentru a verifica dacă totul funcționează conform așteptărilor, voi adăuga o metodă perform_request care va lua calea către punctul API și va returna JSON cu rezultatul solicitării. Pentru autorizare, voi folosi antetul HTTP Authorization, așa cum este indicat în documentația API. Nu îmi place opțiunea cu parametrul de interogare, deoarece nu va funcționa pentru solicitările POST.
# ./lib/groovehq/client.rb # ... def perform_request (cale) url = "https://api.groovehq.com/v1/ # (cale)" răspuns = HTTParty. obține (url, anteturi: ("Authorization" => "Bearer # (@access_token)")) JSON. parse (răspuns. corp) sfârşitul # ...
Să verificăm dacă totul funcționează așa cum ar trebui executând comanda bundle exec irb în folderul gem. Apoi executăm următoarele bucăți de cod una câte una:
necesită "./lib/groovehq.rb" client = GrooveHQ :: Client. client nou ("your_access_token"). perform_request ("eu") # eu este de obicei responsabil pentru returnarea datelor despre proprietarul jetonului
Ca rezultat, dacă se folosește jetonul de acces corect, veți obține un hash cu ceva de genul acesta în consolă:
("agent" => ("e-mail" => " [email protected]"," prenume "=>" Kirill "," prenume "=>" Shirinkin "," href "=> „https://api.groovehq.com/v1/agents/ [email protected]" , "links" => ("bilete" => ("href" => „https://api.groovehq.com/v1/tickets?assignee=fodojyko%40gmail.com” } } } }
Se pare că avem o versiune de lucru minimă a bijuteriei! Commit-ul cu modificările este aici: f7d9eef.
Metoda #perform_request a fost creată doar pentru depanare, deci nu mai conține creație corectă link-strings.
Adăugarea structurii
Ce urmeaza?
Următoarea mea sarcină va fi să adaug cât mai multe resurse posibil urmând documentația API. Despre problemele cu care mă voi confrunta în acest proces - în articolul următor.
Un exemplu de solicitare API care returnează cele mai apropiate 20 de evenimente din Moscova și Sankt Petersburg:
https://api.timepad.ru/v1/events.json?limit=20&skip=0&cities=Moscow,Sankt-Petersburg&fields=location&sort=+starts_at
Să-l analizăm pe părți.
https: // - accesul la API este posibil doar prin https, la încercarea de a primi date prin http, se afișează o eroare 400. Acest lucru vă permite să garantați integritatea datelor și să împiedicați transferul oricăror informații sensibile sub formă necriptată.
api.timepad.ru/v1 - API-ul Timepad este situat pe un domeniu separat, versiunea este încorporată în adresă. Acest lucru se face astfel încât, dacă v2 apare vreodată, trecerea la acesta va fi opțională, iar prima versiune va continua să funcționeze atâta timp cât are clienți.
/ events este o resursă de evenimente, una dintre principalele resurse API. Cu acesta, puteți accesa baza de date a prelegerilor, seminariilor, concertelor, conferințelor, adunărilor și întâlnirilor desfășurate prin Timepad, filtrând într-una din câteva zeci de moduri posibile.
Json - o indicație a formatului de date dorit. Json și html sunt acceptate. Dacă nu este specificat nimic, API-ul detectează automat formatul: html în browser, json în toate celelalte cazuri.
& sort = + starts_at - sortarea după data începerii evenimentului în ordine crescătoare. De asemenea, este posibil să sortați după câțiva alți parametri.
Selectarea câmpurilor de afișat
API-ul evenimentului afișează doar câteva dintre cele mai frecvent utilizate câmpuri de eveniment: titlu, categorie, data de începere, link, poster.
Pentru a afișa alte câmpuri de evenimente, trebuie să le specificați în parametrul câmpuri separate prin virgule, de exemplu:
Ca urmare a unei asemenea cereri în afară de câmpurile implicite vor insera, de asemenea, un obiect loc de desfășurare a evenimentului și un obiect de date suplimentar despre starea de înregistrare pentru eveniment. Obiecte interne fie complet neafisat, fie complet afisat, campul campurilor nu le afecteaza continutul.
Lista câmpurilor care pot fi afișate se găsește în documentația online marcată Opțional ca in captura de ecran:
Sortarea valorilor
API-ul Timepad acceptă sortarea după unul dintre următoarele câmpuri:
Nume
incepe la
oraș
referrer_percent
creat la
id
Numele câmpului de sortare trebuie specificat în cerere, de exemplu:
Pentru a sorta în ordine descrescătoare, trebuie să specificați - înainte de numele câmpului, de exemplu:
https://api.timepad.ru/v1/events?sort=-id
Când sortați în ordine crescătoare, puteți indica opțional un plus înaintea numelui, de exemplu,
Paginare
Toate listele din API sunt împărțite în pagini. Există următorii parametri pentru a le controla:
limită - numărul de elemente de returnat
skip - numărul de elemente de ignorat
Astfel, de exemplu, dacă primiți evenimente până la 10, solicitările vor arăta astfel:
https://api.timepad.ru/v1/events?limit=10
https://api.timepad.ru/v1/events?limit=10&skip=10
https://api.timepad.ru/v1/events?limit=10&skip=20
https://api.timepad.ru/v1/events?limit=10&skip=30
...
etc
În acest caz, răspunsul arată astfel:
("total": "123", "valori": [...])
Totalul reflectă numărul total de elemente din selecție, iar valorile conțin elementele corespunzătoare setării de paginare.
Câmpuri goale
API-ul elimină implicit câmpurile cu valori goale (matrice goale, linii goale, nul). În cazul în care aveți nevoie de valori goale, trebuie să specificați parametrul show_empty_fields cu valoarea true
Bună, Habr!
La un moment dat, navigând pe Internet pentru utilizarea rațională a API-ului Vkontakte, nu am putut găsi ceva inteligibil, singurele biblioteci pe care le-am găsit au fost implementate fără a folosi practici general acceptate și fără frumos cod... Am decis să corectez această neînțelegere și am scris propria bibliotecă pentru a lucra cu API-ul Vkontakte.
Detalii și abordări pline de viață sub habrakat.
S-a întâmplat ca API-ul Vk să fie implementat destul de bine, cu excepția unor puncte nelogice, pe care le voi menționa mai târziu. Dar astăzi nu vorbim despre calitate, ci despre o aplicație specifică.
Imediat este necesar sa fac o rezervare, pe langa descriere, voi aduce bucati de cod de lucru in biblioteca mea, link catre care voi da la finalul articolului. Biblioteca funcționează pe acesta din urmă versiune stabilă 5.5, dacă tăiați generatoarele de la primirea lotului, atunci ar trebui să funcționeze pe 5.4.
- Autorizare server (așa-numita autorizare site)
- Autorizarea clientului (autonom)
- Autorizarea serverului de aplicații
Algoritmul de obținere în primul caz se reduce la implementarea următoarelor puncte:
- Afișăm un link pentru autorizarea utilizatorului, pe care îl formatăm în conformitate cu documentația
- Utilizatorul îl urmărește și se conectează
- Utilizatorul este redirecționat către REDIRECT_URI al aplicației noastre cu codul parametrului GET
- Aplicația noastră trebuie să facă o solicitare către API-ul care conține codul pentru a obține simbolul de acces al utilizatorului
- API-ul răspunde fie cu un obiect care conține simbolul de acces, fie cu o eroare.
Un exemplu de cod cu care puteți porni aceasta nu este o afacere dificilă.
$ auth = getjump \ Vk \ Auth :: getInstance (); $ auth-> setAppId ("3470411") -> setScope ("SCOPE") -> setSecret ("COD SECRET") -> setRedirectUri ("http: //localhost/test.php"); $ token = $ auth-> startCallback (); printf ("LINK", $ auth-> getUrl ());
Se presupune că domeniul nostru este localhost și fișierul curent este test.php. Dacă totul a mers bine, atunci variabila noastră $ token va conține cheia de acces a utilizatorului care a trecut autorizația.
Din momentul în care avem o cheie de acces, putem efectua Solicitări API... Logica generală de solicitare este simplă, transmiteți o solicitare special creată la adresa URL API. Solicitarea trebuie să conțină numele metodei și argumente.
api.vk.com/method/METHOD_NAME?PARAMETERS&access_token=ACCESS_TOKEN
Lista metodelor, acesta este unul dintre lucrurile bogate din API. În ea, puteți găsi metode care nu necesită o cheie de acces pentru munca lor, prin urmare le puteți apela fără a o obține.
Când folosim o bibliotecă, trebuie să creăm un obiect de bază, astfel:
$ vk = getjump \ Vk \ Core :: getInstance () -> apiVersion ("5.5") -> setToken ($ token);
Câteva exemple de interogări folosind biblioteca:
Exact 100 de obiecte care conțin date utilizator de la 1 la 100 vor trece prin funcția anonimă din fiecare. Rețineți că dacă eliminăm apelul funcției, nu se va face nicio solicitare, totul pentru că va fi returnat un obiect care are metodele magice __call și __get suprascrise. , care ne permite să facem o cerere atunci când avem nevoie de ea.
$ vk-> cerere ("users.get", ["user_ids" => interval (1, 100)]) -> fiecare (funcție ($ i, $ v) (dacă ($ v-> last_name == "" ) return; imprimă $ v-> last_name."
";
});
Unul dintre lucrurile care ne dezvăluie utilizarea generatoarelor este preluarea loturilor. Adică primim date doar atunci când avem nevoie. Următorul exemplu ne va permite să primim TOATE mesajele noastre, solicitări pentru 100. Fiți atenți, metodă cere să aveți drepturi pentru mesaje, Aplicații de sine stătătoare, aceeași autorizație și, în consecință, transferul cheii de acces.
foreach ($ vk-> cerere ("messages.get") -> lot (100) ca $ date) ($ date-> fiecare (funcție ($ i, $ m) (if (isset ($ m-> body)) ) print $ m-> body. PHP_EOL;));)
Metoda buna care poate fi găsit în API - a executa... Este nevoie de un parametru de cod ca argument, codul este un fel de pseudo JavaScript care ne permite să ne executăm codul pe partea de server și, de asemenea, ne permite să executăm proceduri stocate pe care le putem crea atunci când edităm aplicația noastră.
Nu am putut ignora acest lucru și l-am implementat în bibliotecă. Pe scurt, vă permite să executați mai multe interogări ca una singură. Uite exemplul următor cod.
$ js1 = $ vk-> cerere ("messages.get", ["count" => 200, "offset" => 0 * 200]) -> toJs (); // Returnează un obiect de tip VkJs $ js2 = $ vk-> cerere ("messages.get", ["count" => 200, "offset" => 1 * 200]) -> toJs (); $ js3 = $ vk-> cerere ("messages.get", ["count" => 200, "offset" => 2 * 200]) -> toJs (); $ js4 = $ vk-> cerere ("messages.get", ["count" => 200, "offset" => 3 * 200]) -> toJs (); $ js1 -> append ($ js2) // Adăugăm js2 la js1 -> append ($ js3) -> append ($ js4) -> execute () // Vrem să facem acest lucru (de fapt returnează RequestTransaction) -> raspuns // Cererea va fi executata abia acum -> fiecare (functie ($ i, $ v) // Prima functie anonima este necesara pentru a parcurge toate elementele matricei primite de la execute (o matrice de 4 elemente, 4 cereri ) ($ v-> fiecare (funcția ($ c, $ d) (// Lângă trecerea în buclă prin toate cele 200 de mesaje din fiecare matrice if (isset ($ d-> body)) print $ d-> body; // Print un mesaj dacă un astfel de câmp este prezent));) );
După cum am promis, una dintre acele neînțelegeri în care ați putea întâlni Versiune curentă Metoda API (5.21).
