Trying the BioID Web Service REST API with Windows PowerShell
In a recent blog post we described how to interact with the BioID Web Service (BWS) RESTful API as an Client App with the cURL command line tool. While this tool is common on UNIX and akin systems the PowerShell is the default scripting environment on Microsoft Windows systems.
Thus we repeat the walk through from the blog post Trying the BioID Web Service REST API with cURL with the equivalent Windows PowerShell commands here. The cmdlets we use for this example require at least Windows PowerShell 3.0.
First contact
If you not done already you first need to register for a free BioID account. After registration you can already play around with biometrics using your web cam or microphone but in this post we want to cover the usage of the API.
First you need to apply for an BWS trial instance and register a sample client app. Trying REST API with cURL is an explanation how. Then you can upload image files and perform biometric operations on those files.
Give me a token
Before we get our token we should prepare the PowerShell environment to save some typing. Open a PowerShell window and use the following commands to set your credentials.
You can use the Get-Credential cmdlet to open a authentication dialog box to enter your Client App Identifier and the secret.
$BWSClientCredentials = Get-Credential
Or you can use following commands to set the credentials in the shell.
$BWSClientSecret = ConvertTo-SecureString "KNGypodPwU9KYddwJRODxftP" -AsPlainText -Force $BWSClientIdentifier = '115243460.9184.app.bioid.com' $BWSClientCredentials = New-Object Management.Automation.PSCredential ($BWSClientIdentifier, $BWSClientSecret)
Next we request the enrollment token and convert it into a header for the Invoke-RestMethod cmdlet.
$BWSEnrollmentToken = Invoke-RestMethod -Credential $BWSClientCredentials -Uri 'https://bws.bioid.com/extension/token?id=115243460.9184.app.bioid.com&bcid=bws.9184.42&task=enroll&livedetection=false'
$BWSEnrollmentTokenHeader = @{"Authorization"="Bearer " + $BWSEnrollmentToken}
Anybody there?
Now we can check if user 42 is already enrolled with images of the face. Therefore we use the isenrolled API call with the BCID of the user.
Invoke-RestMethod -Credential $BWSClientCredentials -Uri 'https://bws.bioid.com/extension/isenrolled?bcid=bws.9184.42&trait=face'
If the user hasn't been enrolled yet the API call returns the error 404 Not Found obviously.
Invoke-RestMethod : The remote server returned an error: (404) Not Found.
If the person is already enrolled the cmdlet will just return silently. With the PowerShell cmdlet Invoke-WebRequest we get a little more verbose output if there are already images (or voice samples) uploaded and a biometric template is present:
Invoke-WebRequest -Credential $BWSClientCredentials -Uri 'https://bws.bioid.com/extension/isenrolled?bcid=bws.9184.42&trait=face'
StatusCode : 200
StatusDescription : OK
Content : {}
RawContent : HTTP/1.1 200 OK
Content-Length: 0
Date: Tue, 26 May 2015 13:55:52 GMT
Server: Microsoft-HTTPAPI/2.0
Headers : {[Content-Length, 0], [Date, Tue, 26 May 2015 13:55:52 GMT], [Server, Microsoft-HTTPAPI/2.0]}
RawContentLength : 0
StatusCode OK tells us there are already some images enrolled.
May I introduce
We need some images converted into Data URL which can be done here.
Now we upload the encoded images a.png.txt and b.png.txt with the following two commands to the BWS:
Invoke-RestMethod -Method POST -Headers $BWSEnrollmentTokenHeader -Uri https://bws.bioid.com/extension/upload -Body (get-content .\a.png.txt) Invoke-RestMethod -Method POST -Headers $BWSEnrollmentTokenHeader -Uri https://bws.bioid.com/extension/upload -Body (get-content .\b.png.txt)
If everything works well following return message is shown in the PowerShell window.
Accepted Warnings Error
-------- -------- -----
True {}
The images are uploaded and can be enrolled with the next command. Since the token has only a limited lifetime you should perform the upload commands and enrollment command without a larger break. Otherwise simply request a new token and start over.
Invoke-RestMethod -Headers $BWSEnrollmentTokenHeader -Uri https://bws.bioid.com/extension/enroll
This return message shows the success of the command.
Success Error ------- ----- True
Checking
Now the isenrolled API call should return a 200 OK.
Invoke-RestMethod -Credential $BWSClientCredentials -Uri 'https://bws.bioid.com/extension/isenrolled?bcid=bws.9184.42&trait=face'
The Invoke-REST method just returns silently if the call succeeded so again you can use the Invoke-WebRequest cmdlet for a more verbose result message.
Invoke-WebRequest -Credential $BWSClientCredentials -Uri 'https://bws.bioid.com/extension/isenrolled?bcid=bws.9184.42&trait=face'
StatusCode : 200
StatusDescription : OK
Content : {}
RawContent : HTTP/1.1 200 OK
Content-Length: 0
Date: Tue, 26 May 2015 14:05:36 GMT
Server: Microsoft-HTTPAPI/2.0
Headers : {[Content-Length, 0], [Date, Tue, 26 May 2015 14:05:36 GMT], [Server, Microsoft-HTTPAPI/2.0]}
RawContentLength : 0
Now we'll try to perform a verification (API) with a third image we haven't enrolled. First we acquire the token for verification, then we upload the image and last we perform the verification API call.
$BWSVerificationToken = Invoke-RestMethod -Credential $BWSClientCredentials -Uri 'https://bws.bioid.com/extension/token?id=115243460.9184.app.bioid.com&bcid=bws.9184.42&task=verify&livedetection=false'
$BWSVerificationTokenHeader = @{"Authorization"="Bearer " + $BWSVerificationToken}
With the token we can now upload the image and perform the verification.
Invoke-RestMethod -Method POST -Headers $BWSVerificationTokenHeader -Uri https://bws.bioid.com/extension/upload -Body (get-content .\c.png.txt) Invoke-RestMethod -Method GET -Headers $BWSVerificationTokenHeader -Uri https://bws.bioid.com/extension/verify
The BWS Result API call returns some more information. It shows if the operation succeeded or not, the action perfomed and the BCID of the individual we performed the operation on.
Invoke-RestMethod -Method GET -Credential $BWSClientCredentials -Uri https://bws.bioid.com/extension/result?access_token=$BWSVerificationToken
Success Action BCID Error
------- ------ ---- -----
True verification bws/9184/42
You can learn more about the RESTful API calls, e.g. result codes or parameters, of the BioID Web Service in our Web API documentation.