Sim:listSims API
などの last_evaluated_key
を指定できる API では、多くの情報を効率よく取得するためにページに分割して情報を取得します。これをページングと呼びます。
たとえば、多くの IoT SIM を所有している場合、Sim:listSims API
を利用して IoT SIM の一覧を取得すると、1 回目の呼び出しではすべてのデータは取得できず、1 ページ目のデータだけが取得できます。残りの IoT SIM の情報 (2 ページ目) を取得するには、1 ページ目のデータとともに返された情報 (具体的には、link
ヘッダーまたは x-soracom-next-key
ヘッダーの値) を指定して、もう一度同じ API を呼びます。
ここでは、3 ページ以上の IoT SIM を持っているとして、Sim:listSims API
ですべての IoT SIM の情報を取得する方法を説明します。
limit
は最大データ数を減らすためのパラメータです
ページングが行われる API では limit
で上限を設定できることがありますが、limit
は最大データ数を減らすためのパラメータです。つまり、すべてのデータが取得できないときに limit
でより大きな値を設定したとしても、取得できるデータは変わりません。すべてのデータを取得できなかった場合は、このページの説明を参考にして、ページごとにデータを取得してください。
API によっては link
ヘッダーまたは x-soracom-next-key
ヘッダーの片方だけが含まれることがあります
API によっては、link
ヘッダーまたは x-soracom-next-key
ヘッダーの片方だけが含まれることがあります。どちらを利用しても同じ結果が得られます。
Sim:listSims API
に限らず、last_evaluated_key
を指定できる API は同様の操作ですべての情報を取得できます。
API キーと API トークンを発行します。
詳しくは、API キーと API トークンの取り扱いについて を参照してください。
Sim:listSims API
を呼び出します。1 ページ目のデータが取得できます。
$ curl -i -X GET https://g.api.soracom.io/v1/sims \ -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \ -H "X-Soracom-Token: $X_SORACOM_TOKEN"
HTTP/2 200 date: Tue, 06 Jun 2023 07:04:19 GMT content-type: application/json cache-control: no-cache link: </v1/sims?last_evaluated_key=1234567890123456780>; rel=next vary: Accept-Encoding x-soracom-next-key: 1234567890123456780 x-soracom-ratelimit-limit: 1000 x-soracom-ratelimit-remaining: 999 x-soracom-ratelimit-seconds-before-refresh: 60 [{"operatorId":"OP1234567890","...},{"operatorId":"OP1234567890","...},...]
次のページが存在する場合は、
link
ヘッダーまたはx-soracom-next-key
ヘッダーに、次のページを取得するための情報が返されます。各ヘッダーで返された値を使って同じ API を呼び出すと次のページを取得できます。link
ヘッダーの場合は、link: </v1/sims?last_evaluated_key=1234567890123456780>; rel=next
の1234567890123456780
を使います。x-soracom-next-key
ヘッダーの場合は、x-soracom-next-key: 1234567890123456780
の1234567890123456780
を使います。
API によっては `link` ヘッダーに `rel=prev` が出力される場合があります
API によっては、
link
ヘッダーに以下のようにrel=prev
とrel=next
が出力される場合があります。link: <xxxxx>; rel=prev, <yyyyy>; rel=next
rel=next
の前に出力される情報 (上記の例ではxxxxx
) は、同じ条件で現在のページを再取得するための情報 (API を呼び出したときに指定した内容) です。rel=prev
の前に出力される情報 (上記の例では、yyyyy
) は、同じ条件で次のページを取得するための情報を取得するための情報です。ヘッダーから取得した
1234567890123456780
をlast_evaluated_key
の値に指定して、もう一度Sim:listSims API
を呼び出します。2 ページ目のデータが取得できます。
$ curl -i -X GET https://g.api.soracom.io/v1/sims?last_evaluated_key=1234567890123456780 \ -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \ -H "X-Soracom-Token: $X_SORACOM_TOKEN"
HTTP/2 200 date: Tue, 06 Jun 2023 07:11:25 GMT content-type: application/json cache-control: no-cache link: </v1/sims?last_evaluated_key=1234567890123456781>; rel=next vary: Accept-Encoding x-soracom-next-key: 1234567890123456781 x-soracom-ratelimit-limit: 1000 x-soracom-ratelimit-remaining: 998 x-soracom-ratelimit-seconds-before-refresh: 46 [{"operatorId":"OP1234567890","...},{"operatorId":"OP1234567890","...},...]
1 回目と同様に、次のページが存在する場合は、
link
ヘッダーまたはx-soracom-next-key
ヘッダーに、次のページを取得するための情報が返されます。各ヘッダーで返された値を使って同じ API を呼び出すと次のページを取得できます。last_evaluated_key 以外の条件を変えないでください
ページングは、多くの情報を効率よく取得するためにページに分割して情報を取得するための機能です。条件を変えると、意図した分割ではないレスポンスが生成されることがあります。
last_evaluated_key
以外の条件を変えないでください。最後のページを取得するまで同じ操作を繰り返します。
最後のページを取得したときは、レスポンスヘッダーに
link
ヘッダーおよびx-soracom-next-key
ヘッダーが含まれません。$ curl -i -X GET https://g.api.soracom.io/v1/sims?last_evaluated_key=1234567890123456781 \ -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \ -H "X-Soracom-Token: $X_SORACOM_TOKEN"
HTTP/2 200 date: Tue, 06 Jun 2023 07:21:53 GMT content-type: application/json cache-control: no-cache vary: Accept-Encoding x-soracom-ratelimit-limit: 1000 x-soracom-ratelimit-remaining: 997 x-soracom-ratelimit-seconds-before-refresh: 39 [{"operatorId":"OP1234567890","...},{"operatorId":"OP1234567890","...},...]