docs: add section for get records by query
This commit is contained in:
Stevan Freeborn
Vendored
+1
@@ -4,6 +4,7 @@
|
||||
"cSpell.words": [
|
||||
"configparser",
|
||||
"DDTHH",
|
||||
"isnull",
|
||||
"markdoc",
|
||||
"Onpsring",
|
||||
"prismjs"
|
||||
|
||||
@@ -34,6 +34,10 @@
|
||||
border-radius: 10px;
|
||||
}
|
||||
|
||||
.snippetContent>pre::-webkit-scrollbar-corner {
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
@-moz-document url-prefix() {
|
||||
.snippetContent>pre {
|
||||
margin-right: 1rem;
|
||||
|
||||
@@ -6,6 +6,10 @@
|
||||
padding: 1rem;
|
||||
}
|
||||
|
||||
.link {
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.title {
|
||||
font-size: 1rem;
|
||||
white-space: nowrap;
|
||||
|
||||
@@ -91,7 +91,7 @@ export default function SideBar({
|
||||
}) {
|
||||
return (
|
||||
<div className={styles.container}>
|
||||
<Link href="/">
|
||||
<Link href="/" className={styles.link}>
|
||||
<h1 className={styles.title}>
|
||||
<span className={styles.onspring}>Onspring</span>{' '}
|
||||
<span className={styles.api}>API</span>
|
||||
|
||||
@@ -68,6 +68,12 @@ export const versionTwo: DocsStructure = {
|
||||
copy: 'copy.md',
|
||||
example: 'example.md',
|
||||
},
|
||||
{
|
||||
title: 'Get Records by Query',
|
||||
folder: 'get_records_by_query',
|
||||
copy: 'copy.md',
|
||||
example: 'example.md',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
@@ -14,7 +14,7 @@ This endpoint returns a single [record](#records) based on the given record id.
|
||||
|
||||
- appId
|
||||
- `number`
|
||||
- The id of the app or survey that the record belongs to.
|
||||
- The id of the app or survey that contains the record.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Retrieving a record from an app
|
||||
|
||||
{% code method="GET" heading="/Records/appId/{appID}/recordId/{recordID}" defaultLanguage="bash" %}
|
||||
{% code method="GET" heading="/Records/appId/{appId}/recordId/{recordId}" defaultLanguage="bash" %}
|
||||
|
||||
```bash
|
||||
curl --location 'https://api.onspring.com/Records/appId/195/recordId/1' \
|
||||
|
||||
@@ -14,7 +14,7 @@ This endpoint returns a [paged](#pagination) collection of [records](#records) f
|
||||
|
||||
- appId
|
||||
- `number`
|
||||
- The id of the app or survey.
|
||||
- The id of the app or survey that contains the records.
|
||||
|
||||
{% /table %}
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Retrieving records for an app
|
||||
|
||||
{% code method="GET" heading="/Records/appId/{appID}" defaultLanguage="bash" %}
|
||||
{% code method="GET" heading="/Records/appId/{appId}" defaultLanguage="bash" %}
|
||||
|
||||
```bash
|
||||
curl --location 'https://api.onspring.com/Records/appId/195' \
|
||||
|
||||
@@ -14,7 +14,7 @@ This endpoint returns a batch of [records](#records) that match the given ids.
|
||||
|
||||
- appId
|
||||
- `number`
|
||||
- The id of the app that contains the records.
|
||||
- The id of the app or survey that contains the records.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# Get Records by Query {% #get-records-by-query %}
|
||||
|
||||
This endpoint returns a [paged](#pagination) collection of [records](#records) for a given app or survey.
|
||||
|
||||
## Query Parameters
|
||||
|
||||
**Note:** [Pagination](#pagination) query parameters can be used to control the number of records returned.
|
||||
|
||||
## Request Body Properties
|
||||
|
||||
{% table %}
|
||||
|
||||
- Property Name
|
||||
- Data Type
|
||||
- Description
|
||||
|
||||
---
|
||||
|
||||
- appId
|
||||
- `number`
|
||||
- The id of the app or survey that contains the records.
|
||||
|
||||
---
|
||||
|
||||
- filter
|
||||
- `string`
|
||||
- A [filter](#filter) expression that will be used to filter the records returned.
|
||||
|
||||
---
|
||||
|
||||
- fieldIds
|
||||
- `number[]`
|
||||
- The ids of the fields to return in the records.
|
||||
|
||||
---
|
||||
|
||||
- dataFormat
|
||||
- `string`
|
||||
- The [format](#data-format) of the field data in the response. Valid values are `raw` and `formatted`. If not specified, `raw` will be used.
|
||||
|
||||
{% /table %}
|
||||
|
||||
## Filter {% #filter %}
|
||||
|
||||
A filter expression is a string that is used to filter records returned by the [Get Records by Query](#get-records-by-query) endpoint. The filter operators available, the fields they are applicable to, and the syntax for each operator are described below.
|
||||
|
||||
{% table %}
|
||||
|
||||
- Operator
|
||||
- Description
|
||||
- Applicable Fields
|
||||
|
||||
---
|
||||
|
||||
- `eq`
|
||||
- Determines if the field equals a value.
|
||||
- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
|
||||
|
||||
---
|
||||
|
||||
- `ne`
|
||||
- Determines if the field does not equal a value.
|
||||
- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
|
||||
|
||||
---
|
||||
|
||||
- `contains`
|
||||
- Determines if the field contains a list value. List value can be its id or name.
|
||||
- `List` fields and formulas with output type of `list`.
|
||||
|
||||
---
|
||||
|
||||
- `isnull`
|
||||
- Determines if the field is null.
|
||||
- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
|
||||
|
||||
---
|
||||
|
||||
- `notnull`
|
||||
- Determines if the field is not null.
|
||||
- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
|
||||
|
||||
---
|
||||
|
||||
- `lt`
|
||||
- Determines if the field is less than a value.
|
||||
- `Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`.
|
||||
|
||||
---
|
||||
|
||||
- `gt`
|
||||
- Determines if the field is greater than a value.
|
||||
- `Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`.
|
||||
|
||||
---
|
||||
|
||||
{% /table %}
|
||||
|
||||
### Delimiters
|
||||
|
||||
When using a string value in a filter expression you must use single quotes (`'`) to delimit the string value. When using a date value in a filter expression you must use single quotes (`'`) to delimit the date value and the delimited value should be preceded by the word `datetime`.
|
||||
|
||||
### Combining Filters
|
||||
|
||||
You can combine multiple filters using the `and` and `or` operators as well as parentheses to control the order of operations. The `not` operator can be used to negate a filter.
|
||||
@@ -0,0 +1,176 @@
|
||||
# Querying for records in an app
|
||||
|
||||
{% code method="POST" heading="/Records/Query" defaultLanguage="bash" %}
|
||||
|
||||
```bash
|
||||
curl --location 'https://api.onspring.com/Records/Query' \
|
||||
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
|
||||
--header 'x-api-version: 2' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"AppId": 195,
|
||||
"Filter": "6983 eq '\''Test Task 5'\''",
|
||||
"FieldIds": [6983,6986,6987,6985,6984],
|
||||
"DataFormat": "Formatted"
|
||||
}'
|
||||
```
|
||||
|
||||
```csharp
|
||||
using Onspring.API.SDK;
|
||||
using Onspring.API.SDK.Models;
|
||||
using Onspring.API.SDK.Enums;
|
||||
|
||||
var onspringClient = new OnspringClient(
|
||||
config.BaseUrl,
|
||||
config.ApiKey
|
||||
);
|
||||
|
||||
var queryRequest = new QueryRecordsRequest
|
||||
{
|
||||
AppId = 195,
|
||||
Filter = "not (6987 lt 10 or 6986 eq 'In Progress') and 6985 gt datetime'2014-03-01T00:00:00.0000000'",
|
||||
FieldIds = new List<int>{ 6983, 6986, 6987, 6985, 6984 },
|
||||
DataFormat = DataFormat.Formatted,
|
||||
};
|
||||
|
||||
var queryResponse = await onspringClient.QueryRecordsAsync(queryRequest);
|
||||
var records = queryResponse.Value.Items;
|
||||
|
||||
foreach (ResultRecord record in records)
|
||||
{
|
||||
Console.WriteLine($"AppId: {record.AppId}, RecordId: {record.RecordId}");
|
||||
|
||||
foreach (RecordFieldValue fieldValue in record.FieldData)
|
||||
{
|
||||
Console.WriteLine($"FieldId: {fieldValue.FieldId}, Type: {fieldValue.Type}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
import {
|
||||
DataFormat,
|
||||
FilterOperators,
|
||||
OnspringClient,
|
||||
QueryFilter,
|
||||
QueryRecordsRequest,
|
||||
} from 'onspring-api-sdk';
|
||||
import dotenv from 'dotenv';
|
||||
dotenv.config();
|
||||
|
||||
const client = new OnspringClient(
|
||||
process.env.BASE_URL,
|
||||
process.env.API_KEY
|
||||
);
|
||||
|
||||
const filter = new QueryFilter(
|
||||
6987,
|
||||
FilterOperators.GreaterThan,
|
||||
0
|
||||
);
|
||||
|
||||
const request = new QueryRecordsRequest(
|
||||
195,
|
||||
filter,
|
||||
[6983, 6986, 6987, 6985, 6984],
|
||||
DataFormat.Formatted
|
||||
);
|
||||
|
||||
const res = await client.queryRecords(request);
|
||||
const records = res.data.items;
|
||||
|
||||
for (const record of records) {
|
||||
console.log(record);
|
||||
}
|
||||
```
|
||||
|
||||
```python
|
||||
from OnspringApiSdk.OnspringClient import OnspringClient
|
||||
from OnspringApiSdk.Models import QueryRecordsRequest
|
||||
from OnspringApiSdk.Enums import DataFormat
|
||||
from configparser import ConfigParser
|
||||
|
||||
cfg = ConfigParser()
|
||||
cfg.read('config.ini')
|
||||
|
||||
key = cfg['prod']['key']
|
||||
url = cfg['prod']['url']
|
||||
|
||||
client = OnspringClient(url, key)
|
||||
|
||||
fieldId = 6983
|
||||
operator = 'eq'
|
||||
value = '\'Test Task 5\''
|
||||
|
||||
request = QueryRecordsRequest(
|
||||
appId=195,
|
||||
filter=f'{fieldId} {operator} {value}',
|
||||
fieldIds=[9686],
|
||||
dataFormat=DataFormat.Formatted.name,
|
||||
)
|
||||
|
||||
response = client.QueryRecords(request)
|
||||
|
||||
print(f'Status Code: {response.statusCode}')
|
||||
print(f'Page Size: {response.data.pageSize}')
|
||||
print(f'Page Number: {response.data.pageNumber}')
|
||||
print(f'Total Pages: {response.data.totalPages}')
|
||||
print(f'Total Records: {response.data.totalRecords}')
|
||||
|
||||
for record in response.data.records:
|
||||
print(f'AppId: {record.appId}')
|
||||
print(f'RecordId: {record.recordId}')
|
||||
|
||||
for field in record.fields:
|
||||
print(f'Type: {field.type}')
|
||||
print(f'FieldId: {field.fieldId}')
|
||||
print(f'Value: {field.GetResultValueString()}')
|
||||
```
|
||||
|
||||
{% /code %}
|
||||
|
||||
{% code heading="RESPONSE" defaultLanguage="json" %}
|
||||
|
||||
```json
|
||||
{
|
||||
"pageNumber": 1,
|
||||
"pageSize": 1,
|
||||
"totalPages": 1,
|
||||
"totalRecords": 1,
|
||||
"items": [
|
||||
{
|
||||
"appId": 195,
|
||||
"recordId": 5,
|
||||
"fieldData": [
|
||||
{
|
||||
"type": "String",
|
||||
"fieldId": 6983,
|
||||
"value": "Test Task 5"
|
||||
},
|
||||
{
|
||||
"type": "String",
|
||||
"fieldId": 6986,
|
||||
"value": "Complete"
|
||||
},
|
||||
{
|
||||
"type": "Integer",
|
||||
"fieldId": 6987,
|
||||
"value": 2
|
||||
},
|
||||
{
|
||||
"type": "String",
|
||||
"fieldId": 6985,
|
||||
"value": "12/31/2021 6:00 AM"
|
||||
},
|
||||
{
|
||||
"type": "String",
|
||||
"fieldId": 6984,
|
||||
"value": "This is a test!"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
{% /code %}
|
||||
Reference in New Issue
Block a user