ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

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 要求オプションを追加します。この構文では、前述の構文の入力引数のいずれかを使用できます。

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

関数を使用してコンテンツを読み取るには、optionsContentReader プロパティを関数のハンドルとして指定します。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 でそのオーディオ形式がサポートされている場合にオーディオ データを返します。サポートされるオーディオ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。

すべて折りたたむ

Hubble Heritage Web サイトから木星のイメージを読み取って表示します。

url = 'http://heritage.stsci.edu/2007/14/images/p0714aa.jpg';
rgb = webread(url);
whos rgb
  Name         Size                 Bytes  Class    Attributes

  rgb       1000x800x3            2400000  uint8              

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

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

木星のイメージ。NASA、ESA および Hubble Heritage Team (STScI/AURA) 提供 (利用条件については Hubble Heritage Information Center を参照)。

World Bank Climate Data API から米国の気温データを読み取ります。1901 年から 2012 年までの気温をプロットします。

World Bank からデータを読み取ります。この API はデータを JSON オブジェクトとして返します。

api = 'http://climatedataapi.worldbank.org/climateweb/rest/v1/';
url = [api 'country/cru/tas/year/USA'];
S = webread(url)
S = 

112x1 struct array with fields:

    year
    data

webread は JSON オブジェクトを構造体配列に変換します。各構造体には、年と、その年における米国の平均気温が摂氏単位で含まれています。

1 年目の気温を表示します。

S(1)
ans = 

    year: 1901
    data: 6.6187

平均気温をプロットします。S.year および S.data を配列に連結し、プロットします。

year = [S.year];
data = [S.data];
plot(year,data)
xlabel('Year');
ylabel('Temperature (Celsius)');
title('USA Average Temperatures')
axis tight

API とデータは World Bank: Climate Data API (API の詳細については World Bank: Climate Data API、および World Bank: Terms of Use を参照してください)。

File Exchange から、Simulink® という語を含み過去 7 日間にアップロードされたファイルを検索します。

クエリ パラメーターを指定します。webread は Web サービス クエリ パラメーターの名前と値を URL に付加します。関数 webread ではなく、File Exchange Web サービスが term および duration のクエリ パラメーターを定義しています。

url = 'https://www.mathworks.com/matlabcentral/fileexchange/';
data = webread(url,'term','simulink','duration',7);

webread は検索結果ページの HTML を文字配列として返します。

追加の要求オプションを指定して、World Bank Climate Data API からデータを文字配列として読み取ります。

weboptions オブジェクトを作成し、その ContentType'text' に設定します。関数 webread は JSON オブジェクトを構造体配列ではなく文字配列に変換します。文字配列の先頭を表示します。

api = 'http://climatedataapi.worldbank.org/climateweb/rest/v1/';
url = [api 'country/cru/tas/year/USA'];
options = weboptions('ContentType','text');
data = webread(url,options);
data(1:62)
ans =

[{"year":1901,"data":6.6187487},{"year":1902,"data":6.4643273}

API とデータは World Bank: Climate Data API (API の詳細については World Bank: Climate Data API、および World Bank: Terms of Use を参照してください)。

Simulink という語を含み過去 7 日間にアップロードされたファイルを File Exchange で検索する、HTTP POST 要求を送信します。

url = 'https://www.mathworks.com/matlabcentral/fileexchange/';
options = weboptions('RequestMethod','post');
data = webread(url,'term','simulink','duration',7,options);

多くの Web サービスでは、データ要求のメソッドとして GET に加えて POST メソッドも提供しています。

NASA Earth Observation (NEO) Web マッピング サービスから 2004 年 12 月の Blue Marble: Next Generation イメージを読み取ります。

datetime オブジェクトを使用して要求するイメージの日付を指定します。DFormat プロパティを指定して、形式を Web サービスで必要な形式に一致させます。

url = 'http://neowms.sci.gsfc.nasa.gov/wms/wms';
D = datetime(2004,12,01,'Format','yyyy-MM-dd');
rgb = webread(url,'Time',D, ...
     'Service','WMS','Layers','BlueMarbleNG-TB','CRS','CRS:84', ...
     'Format','image/jpeg','Height',256,'Width',512, ...
     'BBOX','-180.0,-90.0,180.0,90.0','Version','1.3.0','Request','GetMap');
imshow(rgb)

webread が、Web サービスのクエリ パラメーターの値として使用できる形式に datetime オブジェクトを変換します。サンプルのすべての名前と値のペアは、NEO Web マッピング サービスで指定されたクエリ パラメーターを指定します。

Blue Marble: Next Generation + Topography and Bathymetry イメージは、NASA の Earth Observatory から提供されています。イメージへのアクセスおよびサービスは、NEO Web マッピング サービス (WMS) から提供されています (クレジットおよび利用条件については、NASA Earth Observations を参照してください。WMS クエリのパラメーターについては、NASA Earth Observations のサイト WMS 1.3.0 Capabilities を検索してください)。

入力引数

すべて折りたたむ

Web サービスの URL。文字配列として指定します。Web サービスは RESTful インターフェイスを実装します。詳細については、RESTfulを参照してください。

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

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

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

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

例: webread('https://www.mathworks.com/matlabcentral/fileexchange/','term','webread') は、File Exchange にアップロードされた webread という語を含むファイルのリストを取得します。

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

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

ContentType 指定子

出力タイプ

'auto' (既定)

コンテンツ タイプに応じて自動的に決定される出力タイプ。

'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 コンテンツの数値または論理行列。最初の出力引数がインデックス付きイメージの場合、2 番目の出力引数はカラーマップ、 3 番目の出力引数はアルファ チャネルです。

サポートされるイメージ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。

'audio'

audio/format コンテンツの数値行列。2 番目の出力引数にサンプリング レートを数値スカラーとして含みます。

サポートされるオーディオ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。

'binary'

バイナリ コンテンツ (つまり char 型として処理されないコンテンツ) の uint8 の列ベクトル。

'table'

スプレッドシートおよび CSV (text/csv) コンテンツのスカラー テーブル オブジェクト。

'json'

application/json コンテンツの char、数値、論理値、構造体または cell 配列。

'xmldom'

text/xml または application/xml コンテンツの Java® ドキュメント オブジェクト モデル (DOM) ノード。指定しない場合、関数は XML コンテンツを文字ベクトルとして返します。

'raw'

'text''xmldom' および 'json' コンテンツの char の列ベクトル。関数はその他のすべてのコンテンツ タイプを uint8 の列ベクトルとして返します。

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

出力引数

すべて折りたたむ

Web サービスから読み取ったコンテンツ。スカラー、配列、構造体またはテーブルとして返されます。

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

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

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

詳細

すべて折りたたむ

RESTful

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

ヒント

  • RESTful Web サービス機能によってサポートされていない機能については、HTTP インターフェイスを参照してください。

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

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

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

R2014b で導入