Soracom

Sim:listSims API などの last_evaluated_key を指定できる API では、多くの情報を効率よく取得するためにページに分割して情報を取得します。これをページングと呼びます。

たとえば、多くの IoT SIM を所有している場合、Sim:listSims API を利用して IoT SIM の一覧を取得すると、1 回目の呼び出しではすべてのデータは取得できず、1 ページ目のデータだけが取得できます。残りの IoT SIM の情報 (2 ページ目) を取得するには、1 ページ目のデータとともに返された情報を指定して、もう一度同じ API を呼びます。

ここでは、3 ページ以上の IoT SIM を持っているとして、Sim:listSims API ですべての IoT SIM の情報を取得する方法を説明します。

1. API キーと API トークンを発行します。

   詳しくは、API キーと API トークンの取り扱いについて を参照してください。

2. 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 ヘッダーに、同じ条件で次のページを取得するための情報が返されます。

   API によっては `rel=prev` が出力される場合があります

   API によっては、link ヘッダーに以下のように rel=prev と rel=next が出力される場合があります。

   link: <xxxxx>; rel=prev, <yyyyy>; rel=next
   

   rel=next の前に出力される情報 (上記の例では xxxxx) は、同じ条件で現在のページを再取得するための情報 (API を呼び出したときに指定した内容) です。

   rel=prev の前に出力される情報 (上記の例では、yyyyy) は、同じ条件で次のページを取得するための情報を取得するための情報です。

3. link: </v1/sims?last_evaluated_key=1234567890123456780>; rel=next の /v1/sims?last_evaluated_key=1234567890123456780 の部分を使って、もう一度 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 ヘッダーに、同じ条件で次のページを取得するための情報が返されます。

4. 最後のページを取得するまで同じ操作を繰り返します。

   最後のページを取得したときは、レスポンスヘッダーの link: <xxxxx>; rel=next が含まれません。

   $ 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","...},...]