Soracom

Users

開発者向けツール
Home 開発者向けツール SORACOM API 利用ガイド Getting Started

大量のデータを取得する (ページング)

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 は同様の操作ですべての情報を取得できます。

  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=next1234567890123456780 を使います。
    • x-soracom-next-key ヘッダーの場合は、x-soracom-next-key: 12345678901234567801234567890123456780 を使います。
    API によっては `link` ヘッダーに `rel=prev` が出力される場合があります

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

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

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

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

  3. ヘッダーから取得した 1234567890123456780last_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","...},...]