外部データのロード

Flash Player 9 以降、Adobe AIR 1.0 以降

AIR ランタイムには、外部ソースからデータを読み込むためのメカニズムがあります。外部ソースは、テキストファイルなどの静的コンテンツや、Web スクリプトによって生成されるコンテンツなどの動的コンテンツを提供します。データは様々な形式で書式設定されている可能性があります。そのため、ランタイムには、データのデコードおよびデータへのアクセスのための機能が用意されています。また、データを取得する際に、外部サーバーにデータを送信することもできます。

URLRequest クラスの使用

外部データをロードする API の多くは、URLRequest クラスを使用して必要なネットワーク要求のプロパティを定義します。

URLRequest プロパティ

次の URLRequest オブジェクトのプロパティは、任意のセキュリティサンドボックス内で設定できます。

プロパティ

説明

contentType

URL 要求で送信されるデータの MIME コンテンツタイプです。contentType が設定されていない場合、値は application/x-www-form-urlencoded 形式で送信されます。

data

URL 要求で送信されるデータを含むオブジェクトです。

digest

Adobe® Flash® Player キャッシュに保存(または Adobe® Flash® Player キャッシュから取得)される署名付き Adobe プラットフォームコンポーネントを一意に識別するストリングです。

method

GET や POST などの HTTP 要求メソッドです。AIR アプリケーションのセキュリティドメインで実行されているコンテンツでは、 "GET" "POST" 以外のストリングを method プロパティとして指定できます。任意の HTTP 動詞を指定できます。デフォルトのメソッドは "GET" です。 AIR のセキュリティ を参照してください。

requestHeaders

HTTP 要求に追加される HTTP 要求ヘッダーの配列です。アプリケーションセキュリティサンドボックスの外部で実行されている Flash Player および AIR コンテンツには、ヘッダーの設定に一定の制限が設けられています。

url

要求される URL を指定します。

URLRequest クラスには、AIR アプリケーションセキュリティサンドボックス内のコンテンツでのみ使用可能な次のプロパティが含まれています。

プロパティ

説明

followRedirects

後でリダイレクトするかどうかを指定します。リダイレクトする場合は true (デフォルト値)、リダイレクトしない場合は false を指定します。これは AIR アプリケーションサンドボックスのみでサポートされます。

manageCookies

HTTP プロトコルスタックで、この要求の Cookie を管理するかどうかを指定します。管理する場合は true (デフォルト値)、管理しない場合は false を指定します。このプロパティの設定は AIR アプリケーションサンドボックスのみでサポートされます。

authenticate

この要求の認証要求を処理するかどうかを指定します。処理する場合は true を指定します。このプロパティの設定は AIR アプリケーションサンドボックスのみでサポートされます。デフォルトでは要求を認証します。そのため、サーバーが資格情報を必要とする場合、認証ダイアログボックスが表示されることがあります。URLRequestDefaults クラスを使用して、ユーザー名やパスワードを設定することもできます。 URLRequest のデフォルトの設定(AIR のみ) を参照してください。

cacheResponse

この要求に対する応答データをキャッシュするかどうかを指定します。このプロパティの設定は AIR アプリケーションサンドボックスのみでサポートされます。デフォルトでは応答をキャッシュします( true )。

useCache

この URLRequest がデータを取得する前にローカルキャッシュを調べるかどうかを指定します。このプロパティの設定は AIR アプリケーションサンドボックスのみでサポートされます。デフォルト( true )ではローカルキャッシュバージョンを使用します。

userAgent

HTTP 要求でユーザーエージェントストリングを使用するよう指定します。

URLRequest のデフォルトの設定(AIR のみ)

URLRequestDefaults クラスを使用すると、URLRequest オブジェクトに対して、アプリケーション固有のデフォルト設定を定義できます。例えば、次のコードでは、 manageCookies プロパティおよび useCache プロパティのデフォルト値を設定しています。新たに作成されるすべての URLRequest オブジェクトでは、標準のデフォルト値ではなく、指定した値がこれらのプロパティで使用されます。

air.URLRequestDefaults.manageCookies = false; 
air.URLRequestDefaults.useCache = false;
注意: URLRequestDefaults クラスは、Adobe AIR で実行されているコンテンツに対してのみ定義されます。Flash Player ではサポートされていません。

URLRequestDefaults クラスには、 setLoginCredentialsForHost() メソッドが含まれています。このメソッドを使用すると、特定のホストに対して使用するデフォルトのユーザー名とパスワードを指定できます。ホストは、このメソッドの hostname パラメーターで指定します。ホストには、ドメイン( "www.example.com" など)またはドメインとポート番号( "www.example.com:80" など)を指定できます。 "example.com" "www.example.com" 、および "sales.example.com" は、それぞれ固有のホストと見なされることに注意してください。

これらの資格情報は、サーバーから要求された場合にのみ使用されます。ユーザーがすでに認証されている場合(認証ダイアログボックスを使用した場合など)は、 setLoginCredentialsForHost() メソッドを呼び出しても、認証されたユーザーが変更されることはありません。

次のコードでは、www.example.com に対して送信する要求で使用する、デフォルトのユーザー名とパスワードを設定します。

air.URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X");
URLRequestDefaults の設定は、現在のアプリケーションドメインのみに適用されます。ただし、例外的に、 setLoginCredentialsForHost() メソッドに渡される資格情報は、AIR アプリケーション内で、任意のアプリケーションドメインで実行された要求に対して使用されます。

詳しくは、『 HTML 開発者用 Adobe AIR API リファレンスガイド 』の URLRequestDefaults クラスの項を参照してください。

URI スキーム

標準の URI スキーム(以下参照)は、任意のセキュリティサンドボックスから実行された要求で使用できます。

http: および https:

標準のインターネット URL で使用します(Web ブラウザーで使用する場合と同じ方法)。

file:

ローカルファイルシステムに保存されているファイルの URL を指定するには、 file: を使用します。次に、例を示します。

file:///c:/AIR Test/test.txt 

AIR では、アプリケーションセキュリティサンドボックス内で実行されているコンテンツの URL を定義する際には、次のスキームを使用することもできます。

app:

app: は、インストールされたアプリケーションのルートディレクトリを基準とした相対的なパスを指定する場合に使用します。例えば、次のパスは、インストールされているアプリケーションのディレクトリの resources サブディレクトリを参照しています。

app:/resources 

AIR Debug Launcher(ADL)を使用して AIR アプリケーションを起動する場合、アプリケーションディレクトリはアプリケーション記述ファイルが含まれているディレクトリです。

File.applicationDirectory で作成した File オブジェクトの URL(および url プロパティ)では、次のように app URI スキームを使用します。

var dir = air.File.applicationDirectory; 
dir = dir.resolvePath("assets"); 
air.trace(dir.url); // app:/assets

app-storage:

app-storage: は、アプリケーションのデータ記憶領域ディレクトリを基準とした相対的なパスを指定する場合に使用します。AIR では、インストールされたアプリケーション(およびユーザー)ごとに、一意のアプリケーション記憶領域ディレクトリが作成されます。このディレクトリは、そのアプリケーション固有のデータを格納するための便利な場所として使用できます。例えば、次のパスは、アプリケーション記憶領域ディレクトリの settings サブディレクトリにある prefs.xml ファイルを参照しています。

app-storage:/settings/prefs.xml 

File.applicationStorageDirectory メソッドで作成した File オブジェクトの URL(および url プロパティ)では、次のように app-storage URI スキームを使用します。

var prefsFile = air.File.applicationStorageDirectory; 
prefsFile = prefsFile.resolvePath("prefs.xml"); 
air.trace(prefsFile.url); // app-storage:/prefs.xml

mailto:

mailto スキームは、 navigateToURL() 関数に渡される URLRequest オブジェクトで使用できます。 別のアプリケーションで URL を開く を参照してください。

前述の URI スキームを使用する URLRequest オブジェクトを使用すると、多数の異なるオブジェクト(FileStream オブジェクトや Sound オブジェクトなど)に対する URL 要求を定義できます。また、これらのスキームは、AIR 内で実行されている HTML コンテンツ( img タグの src 属性など)で使用することもできます。

ただし、AIR 固有の URI スキーム( app: および app-storage: )は、アプリケーションセキュリティサンドボックス内のコンテンツでしか使用できません。詳しくは、 AIR のセキュリティ を参照してください。

URL 変数の設定

変数は URL ストリングに直接追加できますが、URLVariables クラスを使用して要求に必要な変数を定義する方が簡単な場合があります。

URLVariables オブジェクトにパラメーターを追加するには、3 つの方法があります。

  • URLVariables コンストラクターで指定する方法

  • URLVariables.decode() メソッドで指定する方法

  • URLVariables オブジェクト自体の動的プロパティとして設定する方法

次の例は、3 つのメソッドすべてと、URLRequest オブジェクトに変数を割り当てる方法を示しています。

var urlVar = new air.URLVariables( "one=1&two=2" ); 
urlVar.decode("amp=" + air.encodeURIComponent( "&" ) ); 
urlVar.three = 3; 
urlVar.amp2 = "&&"; 
air.trace(urlVar.toString()); //amp=%26&amp2=%26%26&one=1&two=2&three=3 
 
var urlRequest = new air.URLRequest( "http://www.example.com/test.cfm" ); 
urlRequest.data = urlVar;

URLVariables コンストラクターまたは URLVariables.decode() メソッドで変数を定義する場合は必ず、URI ストリング内の特別な意味を持つ文字を URL エンコードしてください。例えば、パラメーター名またはパラメーター値でアンパサンドを使用する場合、アンパサンドはパラメーターの区切り文字として機能するので、 & %26 に変更してアンパサンドをエンコードする必要があります。これには、トップレベルの encodeURIComponent() 関数を使用できます。

URLLoader クラスの使用

URLLoader クラスを使用すると、サーバーに要求を送信したり、返された情報にアクセスしたりできます。ローカルファイルへのアクセスが許可されているコンテキストで、ローカルファイルシステム上のファイルにアクセスする場合にも、URLLoader クラスを使用できます。URLLoader クラスは、指定した URL からテキスト、バイナリデータ、または URL エンコード形式の変数をダウンロードする際に使用します。URLLoader クラスは、 complete httpStatus ioError open progress securityError などのイベントを送出します。

URLLoader クラスは、XMLHttpRequest クラスの代替手段を提供します。このいずれかのクラスを使用して、HTTP 要求経由でデータをダウンロードできます。

ダウンロードデータは、ダウンロードが完了するまで使用できません。ダウンロードの進捗状況(ロード済みバイト数と合計バイト数)は、 progress イベントの送出をリッスンすることで監視できます。ただし、ファイルのロードの完了が早すぎると progress イベントは送出されない場合があります。ファイルが正常にダウンロードされた場合、 complete イベントが送出されます。URLLoader の dataFormat プロパティを設定することにより、データをテキスト、生のバイナリデータまたは URLVariables オブジェクト形式で受信できます。

URLLoader.load() メソッドのパラメーターは、URLRequest オブジェクトを指定する request パラメーターの 1 つだけです(URLLoader クラスのコンストラクターにも、必要に応じて同じパラメーターを指定できます)。URLRequest インスタンスには、1 件の HTTP 要求に関して、ターゲット URL、要求メソッド( GET または POST )、付加的なヘッダー情報、MIME タイプおよびその他すべての情報が格納されます。

例えば、XML パケットをサーバーサイドスクリプトにアップロードする場合のコードは次のようになります。

var secondsUTC = new Date().time; 
var dataXML = (new DOMParser()).parseFromString( "<time>" + secondsUTC + "</time>", "application/xml" ); 
var request = new air.URLRequest("http://www.example.com/time.cfm"); 
request.contentType = "text/xml"; 
request.data = dataXML; 
request.method = air.URLRequestMethod.POST; 
var loader = new air.URLLoader(); 
loader.load(request);

上記のコードスニペットでは、サーバーに送信される XML パケットを格納する dataXML という名前の XML ドキュメントを作成します。この例では、URLRequest の contentType プロパティを "text/xml" に設定し、XML ドキュメントを URLRequest の data プロパティに割り当てます。最後に、URLLoader オブジェクトを作成し、 load() メソッドを使用してリモートスクリプトに要求を送信します。

URLStream クラスの使用

URLStream クラスを使用すると、データを受信している最中にダウンロードデータにアクセスできます。URLStream クラスでは、ダウンロードの完了前にストリームを閉じることもできます。ダウンロードされたデータは、生のバイナリデータ形式で利用できます。

URLStream オブジェクトからデータを読み込むときは、 bytesAvailable プロパティを使用して、読み取るデータが十分にあるかどうかを事前に確認します。読み取り可能なデータ量よりも多くのデータを読み取ろうとすると、EOFError 例外がスローされます。

httpResponseStatus イベント(AIR)

URLStream クラスは、応答データが配信される前に、 httpResponseStatus イベントを送出します。HTTPStatusEvent クラスで表わされる httpResponseStatus イベントには、応答を返した URL を示す responseURL プロパティと、応答によって返された応答ヘッダーを表す URLRequestHeader オブジェクトの配列である responseHeaders プロパティが含まれています。

外部ドキュメントからのデータのロード

動的なアプリケーションを作成する場合、外部のファイルまたはサーバーサイドスクリプトからデータをロードするようにすると、アプリケーションの編集と再コンパイルを必要としない動的なアプリケーションを実現できます。例えば、「今日の一言」アプリケーションを作成する場合、サーバーサイドスクリプトで、データベースからランダムに選んだ一言を取得して 1 日 1 回テキストファイルに保存するようにします。そうすれば、 アプリケーションでは静的なテキストファイルをロードするだけでよく、毎回データベースへのクエリを発行する必要はなくなります。

次のコードでは、URLRequest オブジェクトと URLLoader オブジェクトを作成し、それによって "params.txt" という外部のテキストファイルから内容をロードします。

var request = new air.URLRequest("params.txt"); 
var loader = new air.URLLoader(); 
loader.load(request);
デフォルトでは、要求メソッドを定義しない場合、Flash Player および Adobe AIR では HTTP GET メソッドを使用してコンテンツがロードされます。 POST メソッドで要求を送信する場合は、次のように、静的定数 URLRequestMethod.POST を使用して request.method プロパティに POST を設定します。
var request = new air.URLRequest("http://www.example.com/sendfeedback.cfm"); 
request.method = air.URLRequestMethod.POST;

実行時に読み込まれる外部ドキュメント params.txt の内容は次のようなデータです。

monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

このファイルには、 monthNames および dayNames の 2 つのパラメーターが含まれています。各パラメーターの内容は、ストリングとして解析されるカンマ区切りリストです。このリストは String.split() メソッドを使用して分割し、配列に変換できます。

外部データファイル内の変数名には、予約語やプログラミング言語の構成要素を含めないでください。そのような変数名を使用すると、コードの解読やデバッグ作業が困難になります。
データの読み込みが完了すると complete イベントが送出され、次のように、URLLoader の data プロパティで外部ドキュメントのコンテンツを使用できるようになります。
function completeHandler(event) 
{ 
    var loader2 = URLLoader(event.target); 
    air.trace(loader2.data); 
}

リモートドキュメントに名前と値のペアが格納されている場合は、URLVariables クラスを使用し、読み込んだファイルのコンテンツを次のように渡すことでデータを解析できます。

function completeHandler(event) 
{ 
    var loader2 = event.target; 
    var variables = new air.URLVariables(loader2.data); 
    air.trace(variables.dayNames); 
}

外部ファイルから読み込んだ個々の名前/値ペアから、URLVariables オブジェクトの個別のプロパティが作成されます。このコード例にある variables オブジェクトの各プロパティは、ストリングとして扱われます。名前/値ペアの値がアイテムのリストである場合は、次のように String.split() メソッドを呼び出すことでストリングから配列に変換できます。

var dayNameArray = variables.dayNames.split(",");
外部テキストファイルから数値データを読み込むには、トップレベル関数の parseInt() parseFloat() Number() などを使用して値を数値に変換する必要があります。

リモートファイルの内容を文字列としてロードして新しい URLVariables オブジェクトを作成する方法とは別に、 URLLoader.dataFormat プロパティを URLLoaderDataFormat クラスの静的プロパティのいずれかに設定する方法もあります。 URLLoader.dataFormat プロパティに設定できる値は次の 3 つのうちいずれかです。

  • URLLoaderDataFormat.BINARY - URLLoader.data プロパティには、ByteArray オブジェクトに格納されたバイナリデータが含められます。

  • URLLoaderDataFormat.TEXT - URLLoader.data プロパティには、String オブジェクトのテキストが含められます。

  • URLLoaderDataFormat.VARIABLES - URLLoader.data プロパティには、URLVariables オブジェクトに格納された URL エンコードされた変数が含められます。

次のコードでは URLLoader.dataFormat プロパティを URLLoaderDataFormat.VARIABLES に設定しているので、ロードしたデータは自動的に解析されて URLVariables オブジェクトが作成されます。

var request = new air.URLRequest("http://www.example.com/params.txt"); 
var variables = new air.URLLoader(); 
variables.dataFormat = air.URLLoaderDataFormat.VARIABLES; 
variables.addEventListener(air.Event.COMPLETE, completeHandler); 
try 
{ 
    variables.load(request); 
}  
catch (error) 
{ 
    air.trace("Unable to load URL: " + error); 
} 
 
function completeHandler(event) 
{ 
    var loader = event.target; 
    air.trace(loader.data.dayNames); 
}
注意: URLLoader.dataFormat のデフォルト値は URLLoaderDataFormat.TEXT です。

次の例に示すように、外部ファイルから XML を読み込む方法も、URLVariables を読み込む場合と同じです。URLRequest インスタンスと URLLoader インスタンスを作成し、それらを使用してリモート XML ドキュメントをダウンロードします。ファイルのダウンロードが完了すると、 complete イベントが送出され、 trace() 関数によってファイルのコンテンツがコマンドラインに出力されます。

 
var request = new air.URLRequest("http://www.example.com/data.xml"); 
var loader = new air.URLLoader(); 
loader.addEventListener(air.Event.COMPLETE, completeHandler); 
loader.load(request); 
 
function completeHandler(event) 
{ 
    var dataXML = event.target.data; 
    air.trace(dataXML); 
}

外部スクリプトとの通信

URLVariables クラスを使用すると、外部データファイルからデータをロードできるだけでなく、サーバーサイドスクリプトに変数を送信し、サーバーの応答を処理することもできます。例えば、ゲームを作成する場合、ユーザーの得点をサーバーに送信して高得点者リストに掲載できるかどうか確認することや、ユーザーのログイン情報をサーバーに送信して検証することなどが考えられます。サーバーサイドスクリプトでは、ユーザー名とパスワードを処理してデータベースに照会し、入力されたユーザー資格情報が有効かどうかの確認を応答として返します。

次のコードでは、 variables という URLVariables オブジェクトを作成し、このオブジェクトを使用して name という新しい変数を作成しています。次に、変数の送信先となるサーバーサイドスクリプトの URL を指定する URLRequest オブジェクトを作成します。その後、URLRequest オブジェクトの method プロパティに、HTTP POST 要求で変数を送信するように設定します。URL 要求に URLVariables オブジェクトを追加するには、前の例で作成した URLVariables オブジェクトを URLRequest オブジェクトの data プロパティに設定します。最後に、URLLoader インスタンスを作成し、 URLLoader.load() メソッドを呼び出して要求を送信します。

var variables = new air.URLVariables("name=Franklin"); 
var request = new air.URLRequest(); 
request.url = "http://www.[yourdomain].com/greeting.cfm"; 
request.method = air.URLRequestMethod.POST; 
request.data = variables; 
var loader = new air.URLLoader(); 
loader.dataFormat = URLLoaderDataFormat.VARIABLES; 
loader.addEventListener(Event.COMPLETE, completeHandler); 
try 
{ 
    loader.load(request); 
} 
catch (error) 
{ 
    air.trace("Unable to load URL"); 
} 
 
function completeHandler(event) 
{ 
    air.trace(event.target.data.welcomeMessage); 
}

次のコードには、前の例で使用された ColdFusion® greeting.cfm ドキュメントのコンテンツが含まれています。

<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> 
    <cfset Form.Name = "Stranger" /> 
</cfif> 
<cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# 
</cfoutput>