-
Notifications
You must be signed in to change notification settings - Fork 27
Reference of v4 batch
| arguments | description | optional |
|---|---|---|
| calls | A batch of endpoints defined in a json string | NO |
Just like its name.
Batch api offers you a dexterity way to make api endpoints easier to interop with each other.
Tutorial 0x00 Simple way to use batch api
Tutorial 0x01 Variable binding
Tutorial 0x02 Interop with forward api
| status | description |
|---|---|
| 0 | everything is OK |
| -1 | invalid endpoints |
| -2 | invalid endpoints |
| -3 | invalid endpoints |
| -4 | too many endpoints requested |
| -5 | invalid bind variables |
| -6 | bind variables must start with character $ |
| -233 | unknown error occurred |
In the endpoint
| status | description |
|---|---|
| 0 | everything is OK |
| -1 | run expression failed |
| -2 | endpoint not found |
We need a piece of json string that defined the endpoints we want to request.
[
{
"id": 0, // this is an unique id
"endpoint": "song/random" // this is an endpoint we need to access
}
]Then remove all the blanks from the json.
Next, process it via the encodeURIComponent function.
Finally, we got
- %5B%7B%22id%22%3A%200%2C%22endpoint%22%3A%20%22song%2Frandom%22%7D%5D
Then add the api link ahead of the string
- https://example.com/v4/batch?calls= %5B%7B%22id%22%3A%200%2C%22endpoint%22%3A%20%22song%2Frandom%22%7D%5D
Send the request and received the result
{
"status": 0,
"content": [
{
// endpoint 0
"id": 0,
// the result from calling endpoint 'song/random'
"result": {
// endpoint status code
"status": 0,
// endpoint content data
"content": {
"id": "altale",
"rating_class": 1
}
}
}
]
}Congratulations! You could add more endpoints to it in this way under the BOTARCAPI_BATCH_MAX_ENDPOINTS limit.
This is an advanced tutorial about batch api.
Batch api introduces a funny concept named variable binding.
It's a little bit complex than tutorial 0x00.
[
{
"id": 0,
"bind": {"$sid": "id"}, // ← look at this
"endpoint": "song/random"
},
{
"id": 1, // ↓ and $sid
"endpoint": "song/info?songname=$sid"
}
]{"$sid": "id"} stored a key-value pair.
The key "$sid" is a temporary variable we used.
The "id" is actually a javascript expression that can access the result of the current endpoint.
It's designed for reading the data only. This means you cannot assign or create a variable, calling a function, even make a loop in it like the generic javascript expression.
In short, The expression "id" reads the data from the current endpoint and saves the value to the "$sid" variable.
That's is the "variable binding". It's clear and easy.
Next, BotArcAPI will process the endpoints one by one and apply the variable value to the placeholder in the next endpoint url.
We suppose the "$sid" now is "grievouslady". So the endpoint
"song/info?songname=$sid"
will becomes
"song/info?songname=grievouslady"
Our variable has been applied in the next endpoint.
Finally, The result should be
{
"status": 0,
"content": [
{
"id": 0,
"result": {
"status": 0,
"content": {
"id": "clotho",
"rating_class": 0
}
}
},
{
"id": 1,
"result": {
"status": 0,
"content": {
"id": "clotho",
"title_localized": {
"en": "Clotho and the stargazer",
"ja": "クロートーと星の観測者"
},
"artist": "しーけー",
"bpm": "230",
"bpm_base": 230,
"set": "base",
"audioTimeSec": 139,
"side": 0,
"remote_dl": false,
"world_unlock": false,
"date": 1498176000,
"difficulties": [
{
"ratingClass": 0,
"chartDesigner": "小東星",
"jacketDesigner": "yoshimo",
"rating": 2,
"ratingReal": 2,
"totalNotes": 519
},
{
"ratingClass": 1,
"chartDesigner": "小東星",
"jacketDesigner": "yoshimo",
"rating": 5,
"ratingReal": 5,
"totalNotes": 745
},
{
"ratingClass": 2,
"chartDesigner": "小東星",
"jacketDesigner": "yoshimo",
"rating": 7,
"ratingReal": 7.5,
"totalNotes": 1021
}
]
}
}
}
]
}The number of the variable binding is unlimited,
So you can add more bindings into an endpoint like
{"$alice": "alice", "$bob": "bob[0].foo", "$charlie": "charlie.foo.bar[1]"}
Enjoy!
This tutorial tells you how to interop between batch api and forward api.
It's so easy if you have read and understood what is the variable binding.
This is what the endpoints look like
[
{
"id": 0,
"bind": {"$token": "access_token"},
"endpoint": "forward/alloc"
},
{
"id": 1,
"endpoint": "forward/forward/user/me?token=$token"
},
{
"id": 2,
"endpoint": "forward/recycle?token=$token"
}
]
In this tutorial, we bind the access token from forward/alloc.
Then apply it to the url we want to forward. Finally, recycle the token.
If no errors happened, We will get
{
"status": 0,
"content": [
{
"id": 0,
"result": {
"status": 0,
"content": {
"access_token": "1e7a2b575f9dba431cb9711c00bce973",
"valid_time": 10
}
}
},
{
"id": 1,
"result": {
"status": 0,
"content": {
"success": true,
"value": {
"is_aprilfools": false,
"curr_available_maps": [],
"character_stats": [],
"friends": [],
"settings": {
"favorite_character": -1,
"is_hide_rating": false
},
"user_id": 233,
"name": "233",
"user_code": "233",
"display_name": "233",
"ticket": 0,
"character": 0,
"is_locked_name_duplicate": false,
"is_skill_sealed": false,
"current_map": "",
"prog_boost": 0,
"next_fragstam_ts": -1,
"max_stamina_ts": 233,
"stamina": 12,
"world_unlocks": [],
"world_songs": [],
"singles": [],
"packs": [],
"characters": [0, 1],
"cores": [],
"recent_score": [],
"max_friend": 10,
"rating": 0,
"join_date": 233
}
}
}
},
{
"id": 2,
"result": {
"status": 0,
"content": null
}
}
]
}