Soracom

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 の情報を取得する方法を説明します。

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 ヘッダーまたは 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) は、同じ条件で次のページを取得するための情報を取得するための情報です。

3. ヘッダーから取得した 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 以外の条件を変えないでください。

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

   最後のページを取得したときは、レスポンスヘッダーに 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","...},...]