HTTP-Kysely
Tätä esimerkkiä varten selitetään ensin kaikki HTTP:n perusteet. Tämä on tärkeää ymmärrettäväksi rajapinnan toimintaa.
Perusteet
Seuraavat kohdat on huomioitava:
- Pyyntö HTTP:n kautta muodostaa yhteyden asiakkaasta, kunnes palvelin katkaisee yhteyden.
- Kysely tehdään TCP:n kautta porttiin 80 (HTTP suojamaton) ja porttiin 443 (HTTPS salattu).
- Jos portti 80 käytetään http://:n kanssa tai portti 443 https://:n kanssa, portti piilotetaan.
- Yhteyskerros on HTTP/1.1:stä lähtien sellainen, että yhteys jätetään auki jonkin aikaa välttääkseen TCP:n käsittelyn. Tämä ei näy Antcasin valvontanäytössä. Kuitenkin kun aika on umpeutunut, asiakas (Antcas-palvelin) sulkee yhteyden. Aikakatkaisu tulisi olla riittävän korkea.
- Jokainen kysely on täysin taaksepäin yhteensopiva. Se, tukeeko palvelin HTTP/1.0:aa, HTTP/1.1:ä tai HTTP/2:ta, on sama asia.
- Otsake on tapaustunnistamaton. Tämä tarkoittaa, että isot ja pienet kirjaimet eivät ole merkityksellisiä. On kuitenkin joitakin valmistajia, jotka eivät kiinnitä huomiota tähän.
- Merkistö Antcas-ohjauksessa on aina UTF-8. Jos käytetään muita merkistöjä, ne on mahdollisesti muunnettava.
- URL:n enimmäispituus, mukaan lukien kysely, on 2'083 merkkiä.
URL:n rakenne on seuraava:
http://server.tld/getdata?project=you%26i+project&id=25#anker
| Komponentti | Merkitys |
|---|---|
| http:// | Määrittää protokollan. Antcas-ohjaus tukee tällä hetkellä http:ta ja https:ia. |
| server.tld | Määrittää kohdepalvelimen verkkotunnuksen (DNS) tai IP-osoitteen. |
| getdata | Palvelimen URI, joka vastaa kohdesivua, verrattavissa polkuun. |
| ?[...] | ?-merkki erottaa URL:n kyselystä (GET-pyyntö), jonka jälkeen tulevat kaikki lomakedata, jotka kutsutaan myös kyselyksi. Kysely koodataan aina korvaamaan tuettuja merkkejä. |
| #[...] | #-merkki määrittää ankkurin sivulla, jolloin voidaan hypätä haluttuun kohtaan (skrollata). Nämä tiedot eivät lähetetä palvelimelle. Lisäksi tämän alueen ja #-merkin kopioiminen kyselyyn saattaa kutsua eri kohdesivua palvelimella. |
Kohdepalvelinten konfigurointi tehdään vastaavassa HTTP-väylässä.
Kyselyn Rakenne
Kysely koostuu otsakkeesta ja rungosta. Otsake näyttää aina ensimmäisellä rivillä käytetyn menetelmän, URIn ja protokollan.
GET /getdata?project=you%26i+project&id=25 HTTP/1.1
Host: server.tld
Tämä seuraa palvelimen vastausta, joka sisältää tilakoodin. Runko seuraa otsaketta tyhjällä rivillä.
HTTP/1.1 200 OK
Server: Apache2
Content-Type: text/html
<html>Hei maailma</html>
Tilakoodit
Tilakoodit on jaettu ryhmiin, joita määrittää ensimmäinen numero. Lisäksi tilakoodin jälkeen tulee selkeä kuvaus. Tässä on muutamia esimerkkejä:
| Tila | Kuvaus |
|---|---|
| 200 OK | Pyyntö onnistui. |
| 301 Found | Uudelleenohjaus oikealle sivulle. Koska Antcas-ohjaus seuraa linkkejä, tämä vastaus usein piilotetaan. |
| 404 Not Found | Määritetty sivu ei löydy. |
| 500 Internal Server Error | Palvelinvirhe on tapahtunut. |
Menetelmät
GET- ja POST-menetelmät ovat yleisimmin käytettyjä.
| Menetelmä | Kuvaus |
|---|---|
| GET | GET-kysely on oletuskysely. Se ei tue sisältöä. |
| POST | POST-kysely lähettää sisällön palvelimelle. Sisältö voi olla tyhjä. Hyöty on siinä, että sisällölle ei ole pituusrajoitusta. GET-pyynnössä voidaan lähettää vain tietty määrä dataa. |
| PUT | PUT:ia käytetään rajapintojen tiedonvaihtoon. |
| DELETE | DELETE:a käytetään yhdessä PUTin kanssa poistamaan dataa. |
| (muut) | Muita HTTP-menetelmiä tuetaan myös, mutta ne vaativat vastaavan konfiguraation. |
Tunnistautuminen
Useimmat tunnistautumiset tapahtuvat otsakkeessa. On kuitenkin myös pyynnöitä, jotka määritellään kyselyssä tai sisällössä.
Joissain tapauksissa on luotava istunto ennen varsinaista kyselyä. Istunto asetetaan otsakkeeksi Set-Cookie. Tämä eväste on sitten palautettava. Evästeen sisältö on tapaustunnistava, mikä tarkoittaa, että sisältö on kopioitava yhdenmukaisesti. Tässä on yksinkertainen esimerkki:
POST /login HTTP/1.1
Host: server.tld
username=myname&password=1234
Palvelimen vastaus:
HTTP/1.1 200 OK
Server: Apache2
Content-Type: text/html
Set-Cookie: SESSION=vmvbquk7dq6dbbcq
Nyt eväste voidaan käyttää seuraavassa kyselyssä:
GET /opendoor HTTP/1.1
Host: server.tld
Cookie: SESSION=vmvbquk7dq6dbbcq
Vinkkejä
Selaimen kehittäjän konsolissa verkko-osiosta voidaan arvioida ja testata pyyntö. On myös joskus hyvä kopioida tai tarkastella otsaketta.
Konfiguraatio
Antcas-ohjauksessa luodaan HTTP-rajapinta väylän avulla. Väylä konfiguroidaan HTTP-asiakkaaksi. Tähän kirjoitetaan kohdeosoite ja portti (vaadittu). Sen jälkeen kysely konfiguroidaan rakenteessa. Tähän merkitään URL muuttujana viestintäosiossa.
Yksinkertainen Kysely
Yksinkertaisen kyselyn luomiseksi valitaan haluttu tietotyyppi, joka on mieluummin merkkijono (string). Jos lähdössä tapahtuu arvonmuutos, suoritetaan jo kysely. Arvo käytetään suoraan kyselynä.
Monimutkainen Kysely
Monimutkaisempi kysely luodaan HTTP_REQUEST-toimintosarjan avulla. Tähän on asetettava viestinnän tietotyyppi raw-tilaan. Vastaus voidaan arvioida sitten HTTP_RESPONSE-toimintosarjan avulla. On ehdottomasti liitettävä kyselyn tunniste, jotta vastaus voidaan kohdistaa oikein.
Esimerkki
Tässä esimerkissä dataa lähetetään palvelimelle GET-menetelmällä ja vastaus arvioidaan. Täydellinen URL on seuraava:
http://server.tld/getdata?project=you%26i+project&id=25
Jotta dataa voidaan hakea tai lähettää palvelimelta, käytetään seuraavaa esimerkkiä:
Huomautus: Esimerkki ei näytä, miten pyyntö käynnistetään. Se käynnistetään positiivisella reunalla SET-sisääntulossa. Välttääkseen tahattoman kyselyn, DIS-sisääntulo tulisi asettaa tosiarvoon.
Rajapinnan konfiguraatio on seuraava:
