webread

RESTful Web サービスからのコンテンツの読み取り

構文

data = webread(url)

data = webread(url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN)

data = webread(___,options)

[data,colormap,alpha] = webread(___)

[data,Fs] = webread(___)

説明

data = webread(url) は url によって指定された Web サービスからコンテンツを読み取り、data にコンテンツを返します。

Web サービスは、JSON、XML、イメージ、テキストなどのインターネット メディア タイプ形式でデータを返すRESTfulインターフェイスを提供します。

data = webread(url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN) は、1 つ以上のパラメーター名と値のペアで指定されたクエリ パラメーターを url に追加します。クエリをメッセージ本文に挿入するには、webwrite を使用します。クエリ パラメーターは Web サービスによって定義されます。

data = webread(___,options) は weboptions オブジェクト options で指定されたその他の HTTP 要求オプションを追加します。この引数は、前述の構文で任意の入力引数の組み合わせに加えて指定できます。

データを特定の出力タイプとして返すには、options の ContentType プロパティを指定します。

関数を使用してコンテンツを読み取るには、options の ContentReader プロパティを関数のハンドルとして指定します。webread は Web サービスからデータをダウンロードし、指定された関数でデータを読み取ります。

• 複数の出力引数を返す関数のハンドルを指定した場合、webread はすべての出力引数を返します。

• 出力引数を 1 つも返さない関数のハンドル (Image Processing Toolbox™ のビデオ ファイル用の関数 @implay など) を指定した場合、webread は出力引数を返しません。

[data,colormap,alpha] = webread(___) は url で指定された Web サービスからイメージを読み取り、data にイメージを返します。イメージのみを返すには前述の構文を使用します。イメージに関連付けられたカラーマップとアルファ チャネルを返すには、この構文を使用してください。

webread は、HTTP 応答にイメージ メディア タイプを指定する Content-Type ヘッダー フィールドが含まれていて、imread でそのイメージ形式がサポートされている場合にイメージを返します。サポートされるイメージ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。

[data,Fs] = webread(___) は url で指定された Web サービスからオーディオ データを読み取り、data にオーディオ データを返します。オーディオ データのみを返すには前述の構文を使用します。オーディオ データのサンプル レートを Hz 単位で返すには、この構文を使用してください。

webread は、HTTP 応答にオーディオ メディア タイプを指定する Content-Type ヘッダー フィールドが含まれていて、audioread でそのオーディオ形式がサポートされている場合にオーディオ データを返します。サポートされるオーディオ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。

例

Web サイトからのイメージの読み取り

Web サイトからイメージ データを読み取ります。

httpsUrl = "https://requestserver.mathworks.com";
imageUrl = strcat(httpsUrl, "/assets/computerVision.jpg");
rgb = webread(imageUrl);
whos rgb

  Name        Size                Bytes  Class    Attributes

  rgb       360x640x3            691200  uint8              

イメージのサイズを変更して表示します。

rgb = imresize(rgb, 0.6);
imshow(rgb)

気象データの読み取り

CSV データ ファイルから温度を読み取ります。

httpsUrl = "https://requestserver.mathworks.com";
dataUrl = strcat(httpsUrl,"/assets/weatherStation.csv");
data = webread(dataUrl);
time = [data.Time];
temp = [data.TempF];

温度データをプロットします。

plot(time,temp)
xlabel("Time")
ylabel("Temperature (Fahrenheit)")
title("Temperature Over Time");
axis padded

Web サービス クエリ パラメーターの指定

クエリ パラメーターを使用してデータベース レコードを選択できます。

まず、従業員データベースの構造について、そのフィールドを表示して確認します。

httpsUrl = "https://requestserver.mathworks.com";
employeeUrl = strcat(httpsUrl,"/employee");
fieldnames(webread(employeeUrl))

ans = 6×1 cell
    {'id'        }
    {'firstName' }
    {'lastName'  }
    {'occupation'}
    {'age'       }
    {'city'      }

次に、クエリ パラメーター firstName と lastName を使用して従業員のレコードを選択します。

jSmith = webread(employeeUrl,"firstName","John","lastName","Smith")

jSmith = struct with fields:
            id: 1
     firstName: 'John'
      lastName: 'Smith'
    occupation: 'Software Engineer'
           age: '32'
          city: 'Boston'

要求オプションの指定

データを特定の型として返すことができます。

weboptions オブジェクトを作成し、その ContentType を "text" に設定します。指定したオプションを使用して、関数 webread で JSON データが文字配列に変換されます。

httpUrl = "http://requestserver.mathworks.com";
employeeUrl = strcat(httpUrl,"/employee");
options = weboptions("ContentType","text");
sBrown = webread(employeeUrl,"firstName","Sarah",options)

sBrown = 
'[{"id":2,"firstName":"Sarah","lastName":"Brown","occupation":"Software Engineer","age":"28","city":"New York"}]'

入力引数

url — Web サービスへの URL

文字ベクトル | string スカラー

Web サービスへの URL。文字ベクトルまたは string スカラーとして指定します。転送プロトコルを含めます。http と https のみがサポートされます。Web サービスは RESTful インターフェイスを実装します。詳細については、RESTfulを参照してください。

例: webread("https://www.mathworks.com/matlabcentral") は Web ページを読み取り、その HTML を文字配列として返します。

QueryName1,QueryValue1,...,QueryNameN,QueryValueN — Web サービスのクエリ パラメーター

パラメーター名と値のペア

Web サービスのクエリ パラメーター。1 つ以上のパラメーター名と値のペアとして指定します。QueryName 引数は、クエリ パラメーターの名前を指定する文字ベクトルまたは string スカラーでなければなりません。QueryValue 引数は、クエリ パラメーターの値を指定する文字ベクトル、string スカラー、数値、logical 値、または datetime 値でなければなりません。数値、論理値および datetime 値は配列内に含めることもできます。要求の一部として受け入れられるパラメーターは、Web サービスによって定義されます。

QueryValue を datetime 値として指定する場合、その Format プロパティには Web サービスに必要な形式と一貫した値を指定しなければなりません。Format プロパティにタイム ゾーンまたはオフセットが含まれていて、datetime 値にゾーンが指定されていない場合、webread はタイム ゾーンに "Local" を指定します。

QueryValue に配列を使用して複数の値が含まれている場合は、Web サービスによる要求どおりに配列をフォーム エンコードできるように weboptions オブジェクトの ArrayFormat プロパティを指定しなければならないことがあります。

例: webread("https://www.mathworks.com/matlabcentral/fileexchange/","term","webread") は、File Exchange にアップロードされた関数 webread を含むファイルのリストを取得します。term パラメーターは File Exchange Web サービスによって定義されます。

options — 追加の HTTP 要求オプション

weboptions オブジェクト

追加の HTTP 要求オプション。weboptions オブジェクトとして指定します。

weboptions オブジェクトの ContentType プロパティを指定し、そのオブジェクトを入力引数として webread に渡すと、webread は data をそのタイプの出力として返します。次の表に weboptions オブジェクトに指定できる有効なコンテンツ タイプを示します。

ContentType 値	出力タイプ
"auto" (既定)	Web サービスで指定されたコンテンツ タイプに応じて自動的に出力タイプが決定されます。
"text"	コンテンツ タイプを表す文字ベクトル: text/plain text/html text/xml application/xml application/javascript application/x-javascript application/x-www-form-urlencoded Web サービスから拡張子 .m をもつ MATLAB® ファイルが返される場合、この関数はそのコンテンツを文字ベクトルとして返します。
"image"	image/format コンテンツの数値または logical 行列。 サポートされるイメージ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。
"audio"	audio/format コンテンツの数値行列。 サポートされるオーディオ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。
"binary"	バイナリ コンテンツ (つまり char 型として処理されないコンテンツ) の uint8 の列ベクトル。
"table"	スプレッドシートおよび CSV (text/csv) コンテンツのスカラー テーブル オブジェクト。
"json"	application/json コンテンツの char、数値、論理値、構造体、または cell 配列。
"xmldom"	text/xml または application/xml コンテンツの Java® ドキュメント オブジェクト モデル (DOM) ノード。ContentType が指定されていない場合、関数は XML コンテンツを文字ベクトルとして返します。
"raw"	"text"、"xmldom" および "json" コンテンツの char の列ベクトル。関数はその他のすべてのコンテンツ タイプを uint8 の列ベクトルとして返します。

weboptions のプロパティとしてリストされるすべての要求オプションについては、weboptions を参照してください。

出力引数

data — Web サービスからのコンテンツ

スカラー | 配列 | 構造体 | table

Web サービスからのコンテンツ。スカラー、配列、構造体、または table として返されます。

colormap — インデックス付きイメージに関連付けられたカラーマップ

数値配列

インデックス付きイメージに関連付けられたカラーマップ。数値配列として返されます。

alpha — インデックス付きイメージに関連付けられたアルファ チャネル

数値配列

インデックス付きイメージに関連付けられたアルファ チャネル。数値配列として返されます。

Fs — オーディオ データの Hz 単位のサンプル レート

正の数値スカラー

オーディオ データの Hz 単位のサンプル レート。正の数値スカラーとして返されます。

詳細

RESTful

"REST" は、Web サービスの一般的なアーキテクチャ スタイルである "Representational State Transfer" の略です。RESTful インターフェイスは、GET、PUT、POST、DELETE などの標準の HTTP メソッドを提供します。

ヒント

• RESTful Web サービス機能によってサポートされていない機能については、HTTP を使用した MATLAB からの Web サービスの呼び出しを参照してください。

• webread は HTTP GET メソッドと HTTP POST メソッドをサポートします。多くの Web サービスではデータの要求メソッドとして GET と POST の両方が提供されます。HTTP POST 要求を送るには、options の RequestMethod プロパティを "post" に指定します。ただし、webread はクエリ オプションを要求メッセージの本文ではなく url に挿入します。クエリを本文に挿入するには、webwrite を使用します。

• HTTP POST 要求の場合、関数 webread は application/x-www-form-urlencoded メディア タイプのみをサポートします。その他のインターネット メディア タイプのコンテンツの POST 要求を送信するには、webwrite を使用してください。

• この関数は Web ドキュメントの内容を調べずに処理方法を決定します。たとえば、HTML ドキュメントや XML ドキュメントには、多くの場合、ドキュメントの文字エンコードを指定する <meta> タグが含まれています。エンコードが webread の既定のエンコードと異なる場合は、weboptions で目的の CharacterEncoding オプションを指定します。

• プロキシ サーバーの設定を指定する方法の詳細については、プロキシ サーバー認証を参照してください。

拡張機能

スレッドベースの環境

MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

バージョン履歴

R2014b で導入

R2024a: Ctrl+C で MATLAB コマンドの実行が停止

この関数の実行中に Ctrl+C を押すと、MATLAB コマンドの実行が停止します。この動作は、キーボード ショートカットを使用した MATLAB のナビゲーションで説明されている MATLAB の他の機能での Ctrl+C の処理と一致しています。

以前は、ユーザーが try/catch ブロック内でキャッチできるカスタム例外が関数からスローされていました。コードに try/catch ブロックが含まれている場合は、それらを削除してコードを更新できます。

次の表に、R2024a より前とそれ以降で Ctrl+C を押したときに異なる結果になる例を示します。

更新前	更新後
try d = webread(myURL) % User presses Ctrl+C catch ME rethrow(ME); end K>> ME ME = HTTPException with properties: ...	d = webread(myURL) % User presses Ctrl+C Operation terminated by user during matlab.internal.webservices.urlencode>validateURL

参考

関数

• websave | weboptions | webwrite | datetime | jsondecode | audioread | imread | readtable | xmlread

トピック

• プロキシ サーバー認証
• Web サービスからのデータの変換
• MATLAB での日付と時刻の表現
• HTTP を使用した MATLAB からの Web サービスの呼び出し

外部の Web サイト

• Representational State Transfer
• JavaScript Object Notation (JSON)