ThisdocumentdescribestheprotocolusedbytheGoogledataAPIs("GData"),includinginformationaboutwhataquerylookslike,whatresultslooklike,andsoon.
このドキュメントは、GoogledataAPIs("GData")が、どのようなquery(問い合わせ)やresults(結果)が使用されるのかの関連情報を情報を含んでいます。
ForotherinformationabouttheGoogledataAPIs,seetheGoogleDataAPIsOverviewdocument.
GoogledataAPIsについての他の情報は、GoogleDataAPIsOverviewを参照して下さい。
Contents
内容・目次
Audience
対象読者
Examples
例
Requesting a feed or other resource
feedやその他リソースの要求
Inserting a new entry
新しいエントリーの挿入
Searching for a string
文字列の検索
Updating an entry
エントリーの更新
Deleting an entry
エントリーの削除
Protocol details
プロトコル詳細
Document format
ドキュメント・フォーマット
Queries
問い合わせ
Optimisticconcurrency(versioning)
楽観的 同時実行
Authentication
認証
Session state
セッション状態
Additional resources
追加リソース
Audience
対象読者
ThisdocumentisintendedforanyonewantingtounderstandthedetailsoftheXMLformatandprotocolusedbytheGoogledataAPIs.
このドキュメントは、GoogledataAPIsが使用するXMLフォーマットとプロトコルの詳細を知りたい、理解したいと思う人の為に意図される。
IfyoujustwanttowritecodethatusestheGDataclientAPIs,thenyoudon'tneedtoknowthesedetails;instead,
seethelinksinthesidebartodocumentationforthelanguage-specificclientlibraries.
もし、GDataclientAPIsを使用するコードをただ書きたければ、これらの詳細を知る必要はありません。
その代わりに、言語に特化したクラスライブラリに関してのドキュメントへのリンクを参照して下さい。
If you want to understand the protocol, read this document.
もし、あたながプロトコルを理解したい場合には、このドキュメントを読んで下さい。
Forexample,youmaywanttoreadthisdocumenttohelpyouwithanyofthefollowingtasks:
例えば、以下のタスクについてあなたを手助けする為にこのドキュメントを読みたいと理由でもかまいません。
ThisdocumentassumesthatyouunderstandthebasicsofXML,namespaces,syndicatedfeeds,andtheGET,POST,PUT,andDELETErequestsinHTTP,
aswellasHTTP'sconceptofa"resource."Formoreinformationaboutthosethings,seetheAdditionalresourcessectionofthisdocument.
このドキュメントは、XMLやnamespacesやsyndicatedfeedsの基礎知識とHTTPのGET,POST,PUT,,DELETE要求やHTTP'sのリソースコンセプトを理解している前提で記述されています。
それらに関しての詳細な情報については、このドキュメントの追加リソースのセクションを参照して下さい。
This document doesn't rely on any particular programming language;
このドキュメントは、特定のプログラミング言語には依存しません。
youcansendandreceiveGDatamessagesusinganyprogramminglanguagethatletsyouissueHTTPrequestsandparseXML-basedresponses.
HTTPrequestsを送信したりXMLベースのレスポンスを解析
プログラミング言語を使用して、GDataメッセージをHTTPでリクエストを出さたり、、XMLベースのレスポンス(GDataメッセージ)を解析させる事ができます。
Examples
例
ThefollowingexamplesshowbareGDataprotocolrequestsyoumightsendandtheGData-formattedresultsyoumightreceive.
次の例は、送信したrequestsによって受け取るだろうGData-formatted結果のGDataプロトコルそのものを示します。
ForexamplesofhowtosendtherequestsusingJavaandC#,seethelanguage-specificclientlibrarylinksinthesidebar.
JavaとC#を使用したrequestsを送信する例は、それぞれのクラスライブライブラリに特化したドキュメントリンクを参照して下さい。
ForinformationaboutusingGDatawithGoogleCalendar,seetheGoogleCalendarDataAPIdocument.
GoogleカレンダーがもっているGDataに関する情報については、GoogleCalendarDataAPIdocumentを参照して下さい。
Requesting a feed or other resource
Assumethere'safeedcalled/myFeed,andassumethatitcurrentlydoesn'thappentocontainanyentries.
/myFeedというfeedがあると仮定して、そしてそれが現在どんなエントリーを含まないと仮定して下さい。
To see it, send the following request to the server:
それを参照するには、サーバーへ次のリクエストを送信して下さい。
GET /myFeedThe server responds:
200 OK
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Foo</title>
<updated>2006-01-23T16:25:00-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href="/myFeed" rel="self"/>
</feed>
Notethatalthoughthefeeddoesn'tcontainanyentries,itdoescontainmetadata,suchasatitleandanauthor'sname.
feedは、なにもエントリーを含んで無いにも関わらず、タイトルと著者の名前といったメタデータを含む事に注意してください。
Inserting a new entry
To create a new entry, sendaPOSTrequest,andsupplyanewentryinGDataformat:
新しいエントリーを作成する為には、GDataフォーマットで新しいエントリーを作成しPOSTrequestを送信して下さい。
POST /myFeed
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<author>
<name>Elizabeth Bennet</name>
<email>liz@example.com</email>
</author>
<title type="text">Entry 1</title>
<content type="text">This is my entry</content>
</entry>
Notethatyoudon'tsupplyid,link,orupdatedelements;theservercreatesthoseinresponsetoyourPOSTrequest.
id、link、updatedの要素を提供しない事に注意して下さい。;サーバーは、あなたのPOSTrequestに応じてそれらを作成します。
Alsonotethattheauthorofafeeddoesn'thavetobethesamepersonastheauthorofanentry.
さらにfeedの著者が、エントリーの作成と同一人物である必要がないことに注意してください。
The server responds:
201 CREATED
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<id>1</id>
<link rel="edit" href="http://example.com/myFeed/1/1/"/>
<updated>2006-01-23T16:26:03-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@example.com</email>
</author>
<title type="text">Entry 1</title>
<content type="text">This is my entry</content>
</entry>
Searching for a string
Todoafull-textsearchforaparticularstring,sendaGETrequestwiththeqparameter.
特定の文字列用に全文検索を行う為には、qパラメーターを備えたGETrequestを送信して下さい。
For more information about queryparameters, see Query requests.
クエリー・パラメーターの詳細の詳細については、Queryrequestsを参照して下さい。
GET /myFeed?q=This
Theserverrespondswithalltheentriesthatmatchthesearchstring"This".(Inthiscasethere'sonlyone.)
サーバーは、検索文字列"This"とマッチするすべてのエントリーで応答します。(この場合1つだけあります。)
200 OK
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Foo</title>
<updated>2006-01-23T16:26:03-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href="/myFeed" rel="self"/>
<entry>
<id>1</id>
<link rel="edit" href="http://example.com/myFeed/1/1/"/>
<updated>2006-01-23T16:26:03-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@example.com</email>
</author>
<title type="text">Entry 1</title>
<content type="text">This is my entry</content>
</entry>
</feed>
Updating an entry
Toupdateanexistingentry,usePUT,usingtheentry'seditURI(asprovidedbytheserverinthepreviousexample).
すでに存在するエントリーを更新するためには、エントリーの編集URIを使用した、PUTを使用して下さい。(前の例のサーバーによって提供される)
(IfyourfirewalldoesnotallowPUT,thendoanHTTPPOSTandsetthemethodoverrideheaderasfollows:X-HTTP-Method-Override:PUT)
(もし、あなたのファイアーウォールがPUTを許可しない時は、HTTPPOSTでヘッダーメソッドを次の通りにオーバーライドして下さい。(X-HTTP-Method-Override:PUT))
Inthefollowingexample,we'rechangingtheentry'stextfromitsoldvalue("Thisismyentry")toanewvalue("Thisismyfirstentry."):
次の例では、私達は、古い値"Thisismyentry"から新しい値"Thisismyfirstentry."へテキストエントリーを変更しています。
PUT /myFeed/1/1/
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<id>1</id>
<link rel="edit" href="http://example.com/myFeed/1/1/"/>
<updated>2006-01-23T16:28:05-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@example.com</email>
</author>
<title type="text">Entry 1</title>
<content type="text">This is my first entry.</content>
</entry>
The server responds:
200 OK
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<id>1</id>
<link rel="edit" href="http://example.com/myFeed/1/2/"/>
<updated>2006-01-23T16:28:05-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@example.com</email>
</author>
<title type="text">Entry 1</title>
<content type="text">This is my first entry.</content>
</entry>
Note that the edit URI has changed; it now ends with"/2/"insteadof"/1/".
編集URIが、変わった事に注意して下さい。それは今、"/1/"では無く、"/2/"で終わります。
The final number in the edit URI is a version number.
編集URIの最終番号はバージョン・ナンバーである。
Formoreinformationaboutversions,seetheOptimisticconcurrencysectionofthisdocument.
バージョンに関してのより詳細な情報については、この文書内の、楽観的な同時実行のセクションを見てください。
To see the new entry in context, request the entire resource again:
コンテキストで新しいエントリーを見るためには、再度全エントリーを要求して下さい。
GET /myFeedThe server responds:
200 OK
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Foo</title>
<updated>2006-01-23T16:28:05-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href="/myFeed" rel="self"/>
<entry>
<id>1</id>
<link rel="edit" href="http://example.com/myFeed/1/2/"/>
<updated>2006-01-23T16:28:05-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@example.com</email>
</author>
<title type="text">Entry 1</title>
<content type="text">This is my first entry.</content>
</entry>
</feed>
Deleting an entry
Todeleteanexistingentry,sendaDELETErequest,usingtheentry'seditURI(asprovidedbytheserverinthepreviousexample).
既存のエントリーを削除する為には、編集URIを使用してDELETEリクエストを送信してください。(前の例におけるサーバーによって提供された)
(IfyourfirewalldoesnotallowDELETE,thendoanHTTPPOSTandsetthemethodoverrideheaderasfollows:X-HTTP-Method-Override:DELETE.)
(もし、あなたのファイアーウォールがDELETEを許可しない時は、HTTPPOSTのヘッダーメソッドを次の通りにオーバーライドして下さい。(X-HTTP-Method-Override:DELETE.))
DELETE /myFeed/1/2/
The server responds:
200 OK
DoanotherGETtoseethatthefeednowcontainsnoentries:
別のGETが、今のfeedを含まない事を見てください。
GET /myFeedThe server responds:
200 OK
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Foo</title>
<updated>2006-01-23T16:30:11-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href="/myFeed" rel="self"/>
</feed>
If the deletion fails, then the server responds with an error code.
もし削除が失敗した場合、サーバーは、エラーコードで応答します。
For more information, see HTTP status codes, later in this document.
より詳細については、後でこの文書内のHTTPstatuscodesを参照して下さい。
Protocol details
プロトコル詳細
This section describes the GData document format and query syntax.
このセクションは、GDataドキュメント・フォーマット及び、query(問い合わせ)のsyntax(文法。規則)について詳しく記述します。
Document format
ドキュメント・フォーマット
GData, Atom, and RSS 2.0 all share the same basic data model:
GData、AtomとRSS2.0はすべて同じ基本データモデルを共有します:
a container that holds both some global data and anynumberofentries.
グローバルなデータおよびいくつもエントリーのを格納するcontainer(コンテナー)
Foreachprotocol,theformatisdefinedbyabaseschema,butitcanbeextendedusingforeignnamespaces.
それぞれのプロトコルは、基礎のスキーマによって定義されます、しかし、外部のnamespacesを使用して拡張する事が出来ます。
GDatacanuseeithertheAtomsyndicationformat(forbothreadsandwrites)ortheRSSformat(forreadsonly).
GDataは、Atomsyndicationformat(読み取りと書き込みの両方のための)と、RSSformat(読み取り専用の)どちらかを使用することが出来ます
Atom is GData's default format.
Atomは、GDataのデフォルトのフォーマットです。
TorequestaresponseinRSSformat,usethe/alt=rss/parameter;
RSSフォーマットでの応答を要求するためには、/alt=rss/parameter を使用して下さい。
for more information, see Query requests.
詳細については、Queryrequestsを参照して下さい。
WhenyourequestdatainRSSformat,GDatasuppliesafeed(orotherrepresentationoftheresource)inRSSformat.
RSSフォーマットでのデータを要求する場合、GDataはRSSフォーマットでfeed(かリソースの他の表現)を供給します。
Ifthere'snoequivalentRSSpropertyforagivenGDataproperty,GDatausestheAtomproperty,labelingitwithanappropriatenamespacetoindicatethatit'sanextensiontoRSS.
もし、GDataの与えられたpropertyと同等のRSSpropertyが無い場合、GDataは、それがRSSに対する拡張であることを示す適切なネーム空間のラベルを付けてAtomを使用します。
Note:MostGDatafeedsinAtomformatusetheAtomnamespaceasthedefaultnamespacebyspecifyinganxmlnsattributeonthefeedelement;
注:ほとんどのGDatafeedsは、要素でxmlnsattributeを指定することによって、Atomformatの使用にdefaultnamespaceとしてAtomnamespaceを使用します
see the examples section for examples of how to do that.
それを使用する方法に関しては、例セクションを参照して下さい。
Thus,theexamplesinthisdocumentdon'texplicitlyspecifyatom:forelementsinanAtom-formatfeed.
従って、このドキュメント注の例は、明示的にatomを指定しません:Atom-formatfeed要素のためです。
ThefollowingtablesshowtheAtomandRSSrepresentationsoftheelementsoftheschema.
次のテーブルは、原子とRSSのスキーマの要素を表示し示します。
AlldatanotmentionedinthesetablesistreatedasplainXMLandshowsupthesameinbothrepresentations.
これらのテーブルで述べられてないデータは、すべてXMLとして明白に扱われ、両方同じ表現を示します。
Unlessindicatedotherwise,theXMLelementsinagivencolumnareinthenamespacecorrespondingtothatcolumn.
もし他の方法で示されなければ、与えられたカラムのXML要素は、そのカラムに対応するネーム空間にあります。
This summary uses standard XPath notation:
この要約は、標準のXPath表記法を使います:
inparticular,slashesshowtheelementhierarchy,andan@signindicatesanattributeofanelement.
特に,/ (スラッシュ)は要素階層を示し,@印は要素の属性を示す。
In each of the following tables, the highlighted items are required.
次のテーブルで、強調表示された項目は、要求される項目です。
The following table shows the elements of a GData feed:
次のテーブルが、GDatafeedの要素を示します: