원격 콘텐츠를 이용한 개발

이 문서에서는 원격 텍스트(일반적으로 HTML), XML, JSON 및 RSS/Atom 피드 데이터를 가져오고 조작하는 방법을 설명합니다.

목차

  1. 소개
  2. 다양한 콘텐츠 유형 작업
    1. 텍스트를 이용한 개발
    2. XML을 이용한 개발
    3. 피드를 이용한 개발
    4. JSON을 이용한 개발
  3. 인증 유형 설정
  4. 메서드
    1. GET
    2. POST
  5. 캐시 새로 고침

소개

가젯에 사용할 수 있는 가장 멋진 기능 중 하나는 새로운 방법으로 여러 소스의 정보를 조합하거나 기존 정보와 상호 작용할 수 있는 대안을 제공하는 기능입니다. 가젯 API를 통해 가젯이 원격으로 다른 웹 서버 및 웹페이지의 콘텐츠를 가져와서 작업할 수 있습니다.

가젯 API는 원격 웹 콘텐츠에서 검색 및 작업하기 위한 makeRequest(url, callback, opt_params) 함수를 제공하며 다음 인수를 필요로 합니다.

  • String url - 콘텐츠가 있는 URL입니다.
  • Function callback - URL에서 데이터를 가져온 뒤, 그 데이터로 호출할 함수
  • Map.<gadgets.io.RequestParameters, Object> opt_params - 요청에 필요한 추가 매개변수

opt_params 인수를 사용하면 다음 내용을 지정할 수 있습니다.

  • 요청의 콘텐츠 유형(TEXT, XML, FEEDJSON)
  • 요청의 메서드 유형(POST 또는 GET)
  • 요청에 포함할 모든 헤더
  • 인증 유형(NONE, SIGNEDOAUTH )

참고: makeRequest()type="url" 가젯과 함께 사용할 수 없습니다.

가져오는 데이터 유형과 상관없이 makeRequest()에 대한 호출은 동일한 특성을 가집니다.

  • 첫 번째 매개변수는 원격 콘텐츠를 가져오는 데 사용되는 URL입니다.
  • 두 번째 매개변수는 반환된 데이터를 처리하는 데 사용하는 callback 함수입니다.
  • 비동기식입니다. 즉, 모든 작업은 callback 함수 내에서 모두 처리되어야 합니다. callback은 (함수 참조의 형태로) 매개변수로 전달되는 함수입니다. callback은 제3자 개발자에게 특정 처리를 수행하기 위한 실행 프레임워크로의 "연결"을 제공합니다.
  • 바로 반환하므로 반환 값이 없고 요청의 응답이 도착할 때마다 연결된 callback 함수를 호출합니다.

예를 들어 원격 콘텐츠를 텍스트로 가져오는 다음의 짧은 코드를 고려해 보겠습니다. 이 코드는 google.com 웹 페이지의 HTML 텍스트를 가져와서 처음 400자를 표시합니다.

function getHtml() {    
  var params = {};  
  params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;  
  var url = "http://www.google.com";  
  gadgets.io.makeRequest(url, response, params);
};
function response(obj) {  
  //obj.text contains the text of the page that was requested  
  var str = obj.text;
  var html =  str.substr(0,400);  
  document.getElementById('content_div').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(getHtml);

이 예는 makeRequest()가 작동하는 방식의 기본 원리를 보여줍니다.

  1. makeRequest()가 호출되면 가젯 API는 함수로 전달되는 URL에 비동기 HTTP GET 요청을 보냅니다(이 예에서 URL은 http://www.google.com임).
  2. makeRequest()는 즉시 반환을 수행하고 나중에 callback 함수를 호출(이 예에서는 response()를 호출함)하며 이 때 가져오기가 완료됩니다. 이것은 callback 함수 내부 또는 callback 함수가 호출한 함수 내부에 임의의 종속 코드를 넣어야 함을 의미합니다.
  3. makeRequest()는 다음 구조의 자바스크립트 개체를 반환합니다.
{
  data : <parsed data, if applicable>,
  errors : <any errors that occurred>,
  text : <raw text of the response>  
}  

이 개체는 callback 함수에 대해 유일한 인수로 제공됩니다. callback 함수는 반환된 데이터에 대해 작업을 수행합니다. 일반적으로 이 작업은 데이터 일부를 추출하여 HTML 마크업과 결합하고 결과 HTML을 가젯에 렌더링합니다.

다양한 콘텐츠 유형 작업

기본적으로 원격 웹사이트의 콘텐츠는 텍스트 형태로 반환됩니다. opt_params 필드를 사용하여 반환된 콘텐츠 유형이 다음 중 하나가 되도록 설정할 수 있습니다.

  • TEXT -- gadgets.io.ContentType.TEXT
  • DOM -- gadgets.io.ContentType.DOM
  • FEED -- gadgets.io.ContentType.FEED
  • JSON -- gadgets.io.ContentType.JSON

텍스트를 이용한 개발

다음은 CSV(쉼표로 구분된 값) 파일의 데이터를 가져와서 이를 사용하여 개인 주소록에 입력하는 예입니다. 이 예에서는 가져온 콘텐츠의 콘텐츠 유형을 선택사항인 매개변수에서 설정하는 방법을 보여줍니다. response(obj) callback 함수에서 텍스트 값은 obj.text를 사용하여 obj에서 추출합니다.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Fetch Text Example"/>
  <Content type="html">
  <![CDATA[
  <div id="content_div"></div>
  <script type="text/javascript">

  // This example fetches data from a CSV file containing contact information. In the CSV file, 
  // each record consists of a name, email address, and phone number.
  function getContacts() {
    var params = {};  
    params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;  
    var url = "http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/Contacts.csv";
    gadgets.io.makeRequest(url, response, params);
  };
  // Callback function to process the response
  function response(obj) {               
    var responseText = obj.text;  
    // Set CSS for div.
    var html = "<div style='padding: 5px;background-color: #FFFFBF;font-family:Arial, Helvetica;" 
    + "text-align:left;font-size:90%'>"; 

    // Use the split function to extract substrings separated by comma 
    // delimiters.
    var contacts = responseText.split(",");
    // Process array of extracted substrings.
    for (var i = 0; i < contacts.length ; i++) {
      // Append substrings to html.
      html += contacts[i]; 
      html += " ";

      // Each record consists of 3 components: name, email, and
      // phone number. The gadget displays each record on a single
      // line:
      //
      // Mickey Mouse mickey@disneyland.com 1-800-MYMOUSE
      //
      // Therefore, insert a line break after each (name,email,phone)
      // triplet (i.e., whenever (i+1) is a multiple of 3).
      if((i+1)%3 ==0) { 
        html += "<br>";
      }
    }
    html += "</div>";
    // Output html in div.
    document.getElementById('content_div').innerHTML = html;
  }
  gadgets.util.registerOnLoadHandler(getContacts);

 </script>
  ]]>
  </Content>
</Module>

XML을 이용한 개발

DOM(Document Object Model)은 HTML 및 XML 문서를 탐색하기 위한 API입니다. makeRequest()를 사용하여 XML문서를 DOM개체로 가져올 수 있습니다. 가져온 DOM개체는 표준 DOM 자바스크립트 함수를 사용하여 작업할 수 있습니다. 일반적으로 이것은 원하는 데이터를 XML 파일에서 추출하여 HTML 및 CSS 마크업과 결합하고 결과 HTML을 가젯에 렌더링함을 의미합니다.

DOM을 사용하면 웹 콘텐츠가 노드 트리로 구문분석됩니다. 예를 들어 다음 HTML 짧은 코드를 고려해 보겠습니다.

<a href="http://www.google.com/">Google's <b>fast</b> home page.</a>

이 짧은 코드는 이 섹션에서 논의한 주요 노드 유형을 보여줍니다.

  • 요소 노드. 이 짧은 코드에서 요소 노드는 'a''b'입니다. 요소 노드는 문서의 구조를 정의하는 중요한 요소입니다.
  • 텍스트 노드. 이 짧은 코드의 텍스트 노드는 ‘Google’s’, ‘fast’‘home page’'입니다. 텍스트 노드는 항상 요소 노드 내에 들어 있습니다. 즉, 텍스트 노드를 포함하는 요소 노드의 하위 노드입니다.
  • 속성 노드. 이 짧은 코드에는 하나의 속성 노드(href=’http://www.google.com’)가 있습니다. 속성 노드는 상위 요소 노드에 대한 추가 정보를 제공합니다. 속성 노드는 속성을 포함하고 있는 요소 노드의 하위 노드로 간주되지 않습니다. 속성은 요소 노드를 어떻게 처리할 것인가에 대한 암시를 담고 있습니다. 이 주제에 대한 자세한 논의는 다양한 노드 유형 작업을 참조하시기 바랍니다.

다음은 HTML 짧은 코드의 DOM 구조입니다.

DOM 트리

DOM 개체에서 데이터에 액세스하려면 DOM 함수를 사용하여 '트리를 돌아다니며' 필요한 데이터에 도달하기 위한 상위-하위 노드 관계를 탐색합니다.

다음 XML 파일에는 아침 식사 메뉴에 대한 데이터가 들어 있습니다. 최상위 노드는 menu이며 여기에는 여러 개의 food 하위 노드가 있습니다. 또한 menu 노드에는 속성 노드(title="Breakfast Menu")도 있습니다. 각 food 노드에는 name, price, descriptioncalories 하위 노드가 있습니다.

name, pricecalories 노드에는 모두 자체 "텍스트" 하위 노드가 있습니다. 각 description 노드에는 CDATA 하위 노드가 있습니다. CDATA는 독특한 노드 유형입니다. CDATA 섹션은 꺾쇠 괄호와 같이 자칫 마크업으로 여겨질 문자가 포함된 텍스트 블록을 이스케이프 처리하는 데 사용됩니다. CDATA 섹션에서 인식되는 유일한 구분 기호는 CDATA 섹션을 종결하는 ']]>' 문자열입니다.

<?xml version="1.0" encoding="UTF-8" ?>
<menu title="Breakfast Menu">
  <food>
     <name>Early Bird Breakfast</name> 
     <price>$3.95</price> 
     <description><![CDATA[<div style="color:purple; padding-left:25px;">Two eggs any style with your choice of bacon 
or sausage, toast or English muffin.</div>]]></description> 
     <calories>450</calories> 
  </food>

  <food>
     <name>Chocolate Chip Belgian Waffles</name> 
     <price>$7.95</price> 
     <description><![CDATA[<div style="color:purple; padding-left:25px;">Chocolate chip Belgian waffles covered with 
chocolate syrup and whipped cream.</div>]]></description> 
     <calories>900</calories> 
 </food>

     …
</menu>

다음 예제 가젯은 이 XML 파일을 데이터 소스로 사용합니다. 이것은 아침 메뉴를 표시하며 사용자가 칼로리 제한을 설정하도록 합니다. 지정된 한도를 초과하는 칼로리는 빨간색으로 표시됩니다. 사용자는 각 아침 메뉴에 대한 설명 표시 여부를 선택할 수도 있습니다.

다음 코드는 다양한 노드 유형의 데이터를 추출하기 위해 DOM 트리를 탐색하는 방법과 이러한 데이터를 HTML 및 CSS 마크업과 결합하여 아침 식사 메뉴 가젯에 표시하는 방법을 보여줍니다.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Fetch XML" scrolling="true"/>
  <UserPref 
    name="mycalories" 
    display_name="Calorie limit" 
    default_value="800"/>
  <UserPref 
    name="mychoice" 
    display_name="Show Descriptions" 
    datatype="bool" 
    default_value="false"/>
  <Content type="html">
  <![CDATA[
    <div id="content_div"></div>
    <script type="text/javascript">
      // get prefs
      var prefs = new gadgets.Prefs();
      // Calorie limit set by user
      var calorieLimit = prefs.getString("mycalories");
      // Indicates whether to show descriptions in the breakfast menu    
      var description = prefs.getBool("mychoice");

      function makeDOMRequest() {    
        var params = {};  
        params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.DOM;  
        var url = "http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/breakfast-data.xml";  
        gadgets.io.makeRequest(url, response, params);
      };
      function response(obj) { 
        // Start building HTML string that will be displayed in <div>.           
        // Set the style for the <div>.        
        var html = "<div style='padding: 5px;background-color: #ccf;font-family:Arial, Helvetica;" 
          + "text-align:left;font-size:90%'>";   
        // Set style for title.
        html +="<div style='text-align:center; font-size: 120%; color: yellow; " 
          + "font-weight: 700;'>"; 
        // obj.data contains a Document DOM element corresponding to the
        // page that was requested
        var domdata = obj.data;

        // Display menu title. Use getElementsByTagName() to retrieve the <menu> element.
        // Since there is only one menu element in the file,
        // you can get to it by accessing the item at index "0". 
        // You can then use getAttribute to get the text associated with the
        // menu "title" attribute.
        var title = domdata.getElementsByTagName("menu").item(0).getAttribute("title");

        // Alternatively, you could retrieve the title by getting the menu element node
        // and calling the "attributes" function on it. This returns an array
        // of the element node's attributes. In this case, there is only one
        // attribute (title), so you could display the value for the attribute at
        // index 0. For example:
        // 
        // var title = domdata.getElementsByTagName("menu").item(0).attributes.item(0).nodeValue; 

        html += title + "</div><br>"; 
        // Get a list of the <food> element nodes in the file
        var itemList = domdata.getElementsByTagName("food");
 
        // Loop through all <food> nodes
        for (var i = 0; i < itemList.length ; i++) { 
        // For each <food> node, get child nodes.
        var nodeList = itemList.item(i).childNodes;

        // Loop through child nodes. Extract data from the text nodes that are
        // the children of the associated name, price, and calories element nodes.
        for (var j = 0; j < nodeList.length ; j++) {
          var node = nodeList.item(j);
          if (node.nodeName == "name") 
          {
            var name = node.firstChild.nodeValue;
          }
          if (node.nodeName == "price") 
          {
            var price = node.firstChild.nodeValue;
          }
          if (node.nodeName == "calories") 
          {
            var calories = node.firstChild.nodeValue; 
          }
          // If the user chose to display descriptions and
          // the child node is "#cdata-section", grab the 
          // contents of the description CDATA for display.
          if (node.nodeName == "description" && description==true)
          {
            if (node.firstChild.nodeName == "#cdata-section") 
              var data = node.firstChild.nodeValue;
          }
        } 
        // Append extracted data to the HTML string.
        html += "<i><b>";
        html += name;
        html += "</b></i><br>";
        html += "&emsp;"; 
        html += price;
        html += " - ";
        // If "calories" is greater than the user-specified calorie limit,
        // display it in red.
        if(calories > calorieLimit) {
          html += "<font color=#ff0000>";
          html += calories + " calories";
          html += " </font>"; 
        }
        else
          html += calories + " calories";
        html += "<br>";
        // If user has chosen to display descriptions
        if (description==true) 
        {
          html += "<i>" + data + "</i><br>";
        } 
      } 
      // Close up div
      html += "</div>";
      document.getElementById('content_div').innerHTML = html;
    };
    gadgets.util.registerOnLoadHandler(makeDOMRequest);
    </script>
  ]]>
  </Content>
</Module>

이 코드 샘플은 DOM 데이터로 작업하기 위해 사용하는 기본 함수 중 네 가지를 보여줍니다.

  • getElementsByTagName(tagname)-- DOM 문서에 대해 tagname과 일치하는 이름을 갖는 요소 노드의 배열을 반환합니다. response.getElementsByTagName("*")에서처럼 와일드카드 문자(*)를 사용하여 파일에서 모든 요소 노드를 검색할 수도 있습니다.
  • getElementById(id)-- DOM 문서에 대해 ID로 단일 노드를 검색합니다.
  • getAttribute(attrib)-- 요소 노드에 대해 속성 attrib를 반환합니다. 예: response.getElementsByTagName("menu").item(0).getAttribute("title").
  • attributes -- 요소 노드의 속성 배열을 반환합니다.

이 예는 DOM 트리를 탐색하기 위한 다양한 함수 중 몇 가지만 보여줍니다. 그 외 시도해 볼 수 있는 것에는 lastChild, nextSibling, previousSiblingparentNode가 있습니다.

다양한 노드 유형 작업

DOM을 사용하여 효과적으로 작업하려면 다양한 노드 유형 사이에 때로 미묘한 차이가 있음을 이해해야 합니다.

노드 유형 설명 반환 값 문제
element <p> , <b> 또는 <calories>와 같이 문서의 구조적 구성 요소입니다. nodeName: 꺾쇠 괄호 안에 들어 있는 모든 텍스트입니다. 예를 들어 <menu>nodeName'menu'입니다.

nodeType: 1

nodeValue : null
요소의 nodeValuenull입니다. 요소와 연결된 텍스트 또는 속성 노드의 값을 구하려면 해당 노드로 이동해야 합니다. 예를 들어 텍스트의 경우에는 element.firstChild.nodeValue이고 속성의 경우에는 element.getAttribute(attrib)입니다.
text 텍스트입니다. 텍스트 노드는 항상 요소에 들어 있으며, 요소의 하위입니다. nodeName: #text

nodeType: 3

nodeValue: 노드에 들어 있는 모든 텍스트입니다.
일부 브라우저는 문서의 모든 여백을 텍스트 노드로 표시하므로 DOM 개체에 '빈' 텍스트 노드가 생깁니다. 이로 인해 트리를 탐색할 때 예상하지 못한 결과가 발생할 수 있습니다. 해결 방법은 뉴라인 문자만 들어 있는 텍스트 노드를 필터링하는 것처럼 간단할 수도 있고 또는 더 강력한 처리를 수행할 수도 있습니다. 이 주제에 대한 자세한 논의는 DOM의 여백을 참조하시기 바랍니다.
attribute 요소 노드에 대한 추가 정보를 제공하는 키-값 쌍(예: title=”my document”)입니다. 속성은 요소 노드에 들어있지만 요소 노드의 하위는 아닙니다. nodeName: 속성 쌍의 왼쪽 값입니다. 속성이 title=”my document”일 경우 nodeNametitle입니다.

nodeType: 2

nodeValue: 속성 쌍의 오른쪽 값(이 예에서는 “my document”)입니다.
속성은 노드이고 요소 노드에 포함되어 있지만 요소의 하위 노드는 아닙니다. 속성은 Node 인터페이스에서 상속하지만 DOM은 속성을 DOM 트리의 일부로 간주하지 않습니다. 이것은 속성 노드(nodeName, nodeValuenodeType 등)에서 대부분의 노드 함수를 사용할 수 있지만, DOM 트리 탐색 함수를 사용하여 속성 노드에 액세스할 수는 없음을 의미합니다. 속성에 액세스하려면 attributesgetAttribute(attrib) 함수를 사용합니다.
CDATA 콘텐츠 데이터만을 가지는 섹션이며, 해석하지는 않습니다. CDATA 섹션은 자칫 마크업으로 여겨질 문자가 포함된 텍스트 블록을 이스케이프 처리하는 데 사용됩니다. CDATA 섹션에서 인식되는 유일한 구분 기호는 CDATA 섹션을 종결하는 "]]>" 문자열입니다. nodeName: #cdata-section

nodeType: 4

nodeValue: CDATA 구분 기호 안의 텍스트 및 마크업입니다.

CDATA 섹션의 텍스트에는 자체 마크업이 있습니다. 이 마크업은 섹션 데이터를 가젯에 통합하는 방법에 대한 암시를 나타낼 수 있습니다.
기타 리소스

피드를 이용한 개발

URL을 콘텐츠 디렉토리의 URL로 추가 양식에 입력하여 iGoogle 페이지에 피드를 추가할 수 있습니다. 여기에서는 가젯 API 내장 피드 지원을 사용하여 피드용 가젯을 만들고 iGoogle에 추가합니다. 사용하기는 쉽지만, 콘텐츠 내용이나 화면 표시방법을 수정할 수는 없습니다. 또한 다른 컨테이너에서 사용할 수 없습니다.

피드를 좀 더 정교하게 처리하기 위해 makeRequest() 메서드를 사용하여 FEED 콘텐츠 유형을 지정할 수 있습니다. 피드 요청은 ATOM 또는 RSS XML 피드를 구문분석하고 JSON으로 인코딩된 개체로서 응답을 반환합니다.

FEED 콘텐츠 유형에 대해 다음 매개변수를 지정할 수 있습니다.

매개변수 데이터 유형 설명
gadgets.io.RequestParameters.NUM_ENTRIES Number, 선택사항 피드에서 가져올 피드 항목 수이며 허용 범위는 1부터 100까지입니다. 기본값은 3입니다.
gadgets.io.RequestParameters.GET_SUMMARIES Boolean, 선택사항 피드에 있는 항목에 대해 전체 텍스트 요약을 가져올 지 여부이며 기본값은 false입니다. 데이터를 사용하려는 경우에만 true로 설정해야 합니다. 전체 요약은 용량이 매우 클 수 있으므로 불필요하게 전송해서는 안 됩니다.

다음은 JSON 피드 개체에 있는 필드입니다.

필드 설명
ErrorMsg 정의되는 경우, 발생한 오류에 대해 설명합니다.
URL RSS/Atom 피드의 URL입니다.
Title 피드의 제목입니다.
Description 피드의 요약정보 또는 설명입니다.
Link 보통 피드 홈페이지의 URL입니다.
Author 피드 작성자입니다.
Entry 피드 항목의 배열입니다. 다음 필드는 Entry 내에서 중첩됩니다.
  • Title. 이 피드 항목의 제목입니다.
  • Link. 이 피드 항목의 URL입니다.
  • Summary. 이 피드 항목의 콘텐츠 또는 요약입니다.
  • Date. 1970년 1월 1일 이후 이 항목에 대한 초 단위 타임스탬프입니다. 자바스크립트 Date 개체를 초기화하려면, 1000을 곱하여 밀리초로 변환한 값을 사용합니다. 예를 보려면 아래의 예제 가젯 코드를 참조하시기 바랍니다.

예를 들어 다음의 RSS 피드를 고려해 보겠습니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<rss version="2.0">
<channel>
<title>Code Examples for makeRequest()</title>
<link>http://code.google.com/apis/gadgets/docs/remote-content.html</link>
<description>This feed lists code examples for the gadgets.* makeRequest() function.</description>
<language>en</language>
<item>
<title>Fetch Text Example</title>
<link>http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/fetch-csv.xml</link>
<description>This example illustrates how to use makeRequest() with text content.</description>
<author>Google</author>
<pubDate>Sat, 09 Aug 2008 11:46:09 UT</pubDate> </item>
<item>
<title>Fetch XML Example</title>
<link>http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/fetch-XML.xml</link>
<description>This section describes how to use makeRequest() with XML content.</description>
<author>Google</author>
<pubDate>Sat, 09 Aug 2008 11:46:09 UT</pubDate>
</item>
<item>
<title>Feed Fetch Example</title>
<link>http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/feed-fetch.xml</link>
<description>This example illustrates how to use makeRequest() with Feed content.</description>
<author>Google</author>
<pubDate>Sat, 09 Aug 2008 10:33:09 UT</pubDate>
</item>
<item>
<title>Fetch JSON Example</title>
<link>http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/fetch-json.xml</link>
<description>This example illustrates how to use makeRequest() with JSON content.</description>
<author>Google</author>
<pubDate>Sat, 09 Aug 2008 03:55:28 UT</pubDate> </item>
</channel>
</rss>

FEED 콘텐츠 유형으로 위의 피드를 가져올 경우 반환된 값은 다음과 같이 JSON 문자열로 인코딩됩니다.

{"Entry":
  [
    {
      "Link":"http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/fetch-csv.xml",
      "Date":1218282369000,
      "Title":"Fetch Text Example",
      "Summary":"This example illustrates how to use makeRequest() with text content."
    },
    {
      "Link":"http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/fetch-XML.xml",
      "Date":1218282369000,
      "Title":"Fetch XML Example",
      "Summary":"This section describes how to use makeRequest() with XML content."
    },
    {
      "Link":"http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/feed-fetch.xml",
      "Date":1218277989000,
      "Title":"Feed Fetch Example",
      "Summary":"This example illustrates how to use makeRequest() with Feed content."
    },
    {
      "Link":"http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/fetch-json.xml",
      "Date":1218254128000,
      "Title":"Fetch JSON Example",
      "Summary":"This example illustrates how to use makeRequest() with JSON content."
    }
  ],
  "Description":"This feed lists code examples for the gadgets.* makeRequest() function.",
  "Link":"http://code.google.com/apis/gadgets/docs/remote-content.html",
  "Author":"Google",
  "URL":"http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/sample-gadgets-feed.xml",
  "Title":"Code Examples for makeRequest()"
}
    

다음 예는 makeRequest()를 사용하여 피드를 가져와서 가젯에 피드의 데이터 일부를 표시하는 방법을 보여줍니다. 이 가젯은 가젯 개발자 포럼에서 여러 항목이 저장된 피드를 가져옵니다. 이를 통해 사용자는 다음을 지정할 수 있습니다.

  • 표시할 항목의 수
  • 가젯에 각 항목의 날짜를 표시할지 여부
  • 가젯에 각 항목의 요약을 표시할지 여부

다음은 이 예의 코드입니다.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Fetch Feed Example" 
    title_url="http://groups.google.com/group/Google-Gadgets-API" 
    scrolling="true">
  </ModulePrefs>
  <UserPref name="show_date" display_name="Show Dates?" datatype="bool" default_value="false"/>
  <UserPref name="num_entries" display_name="Number of Entries:" default_value="5"/>
  <UserPref name="show_summ" display_name="Show Summaries?" datatype="bool" default_value="false"/>
  <Content type="html">
  <![CDATA[
  <style> #content_div { font-size: 80%;  margin: 5px; background-color: #FFFFBF;} </style>
  <div id="content_div"></div>
  <script type="text/javascript">

  // Get userprefs
  var prefs = new gadgets.Prefs();
  var showdate = prefs.getBool("show_date");
  var entries = prefs.getInt("num_entries");
  var summaries = prefs.getBool("show_summ");

  function getFeed() {  
    var params = {};  
    params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.FEED;  
    params[gadgets.io.RequestParameters.NUM_ENTRIES] = new Number(entries);  
    params[gadgets.io.RequestParameters.GET_SUMMARIES] = summaries; 
    var url = "http://groups.google.com/group/Google-Gadgets-API/feed/rss_v2_0_msgs.xml";  
    gadgets.io.makeRequest(url, response, params);
  };

  function response(obj) { 
    // obj.data contains the feed data
    var feed = obj.data;
    var html = "";

    // Display the feed title and description
    html += "<div><b>" + feed.Title + "</b></div>";
    html += "<div>" + feed.Description + "</div><br>";
      
    // Access the data for a given entry
    if (feed.Entry) {
      for (var i = 0; i < feed.Entry.length; i++) {
        html += "<div>"
          + "<a target='_blank' href='" + feed.Entry[i].Link + "'>"
          + feed.Entry[i].Title
          + "</a> ";
        if (showdate==true)
        { 
          // The feed entry Date field contains the timestamp in seconds
          // since Jan. 1, 1970. To convert it to the milliseconds needed
          // to initialize the JavaScript Date object with the correct date, 
          // multiply by 1000.
          var milliseconds = (feed.Entry[i].Date) * 1000; 
          var date = new Date(milliseconds); 
          html += date.toLocaleDateString();
          html += " ";
          html += date.toLocaleTimeString(); 
        }
        if (summaries==true) { 
          html += "<br><i>" + feed.Entry[i].Summary + "</i>";
        }
        html += "</div>";
      }
    }        
    document.getElementById('content_div').innerHTML = html;
  };
  gadgets.util.registerOnLoadHandler(getFeed);
  </script>
  ]]>
  </Content>
</Module>

JSON을 이용한 개발

JSON(JavaScript Object Notation)은 특정 유형의 개체(배열 및 키-값 쌍의 모음)를 문자열로 인코딩하여 쉽게 전달할 수 있는 데이터 교환 형식입니다. JSON 콘텐츠 유형을 사용하면 JSON으로 인코딩된 콘텐츠를 자바스크립트 개체로 가져올 수 있습니다.

아래 가젯은 다음의 JSON 인코딩 문자열이 들어있는 텍스트 파일의 콘텐츠를 가져옵니다.

{"Name" : "Rowan", "Breed" : "Labrador Retriever", "Hobbies" : ["fetching", "swimming", "tugging", "eating"]}

이 문자열이 들어있는 텍스트 파일의 콘텐츠를 가져올 때 반환 값은 키-값 쌍(즉, 결합된 배열)이 들어있는 자바스크립트 개체입니다. 이 샘플은 개체를 검색한 다음 들어있는 키-값 쌍을 인쇄합니다. 이 값이 배열(대괄호 []로 표시)일 경우에는 배열 콘텐츠가 글머리기호 목록으로 바뀝니다.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Fetch JSON Example"/>
  <Content type="html">
  <![CDATA[
    <div id="content_div"></div>
    <script type="text/javascript">

    function makeJSONRequest() {    
      var params = {};
      params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.JSON;
      // This URL returns a JSON-encoded string that represents a JavaScript object
      var url = "http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/json-data.txt";
      gadgets.io.makeRequest(url, response, params);
    };

    function response(obj) { 
      var jsondata = obj.data;
      var html = "";
      // Process returned JS object as an associative array
      for (var key in jsondata) {
        var value = jsondata[key];
        html += key + ": ";
        // If 'value' is an array, render its contents as a bulleted list
        if (value instanceof Array)
        {
          html += "<br /><ul>";
          for (var i = 0; i < value.length ; i++)
          {
            html += "<li>"+ jsondata.Hobbies[i] + "</li>";
          }
          html+= "</ul>";
        }  
        // If 'value' isn't an array, just write it out as a string
        else {        
          html += value + "<br />";
        }      
      }               
      document.getElementById('content_div').innerHTML = html;
     };
     gadgets.util.registerOnLoadHandler(makeJSONRequest);
     </script>
  ]]>
  </Content>
</Module>

다음은 가젯의 출력 결과입니다.

Name: Rowan
Breed: Labrador Retriever
Hobbies:

  • fetching
  • swimming
  • tugging
  • eating

JSON 추가 정보

가젯 API는 개체를 JSON 문자열로 인코딩하는 gadgets.json.stringify() 메서드와 JSON 문자열을 개체로 변환하는 gadgets.json.parse() 메서드를 제공합니다. 오픈소셜은 응용프로그램 데이터를 포함한 모든 반환된 데이터에 대해 자동 HTML 이스케이프 처리를 수행하므로, 응용프로그램에 저장되어 있는 문자로 인코딩된 JSON 개체를 구문분석하기 전에는 언이스케이프 처리를 수행해야 합니다(예: gadgets.util.unescapeString(jsondata)).

이 예에서는 자바스크립트 배열을 만들어 JSON 문자열로 인코딩한 다음 JSON 문자열을 다시 배열 개체로 변환합니다.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="JSON Example" />
  <Content type="html">
  <![CDATA[
     <div id="content_div"></div>
     <script type="text/javascript">
     var html = "";
     // Create Array object
     var myfriends = new Array();
     myfriends[0] = "Touki";
     myfriends[1] = "Rowan";
     myfriends[2] = "Trevor";

     // Encode array as JSON string
     var jsonString = toJSON(myfriends);
     html += "The JSON string is " + jsonString + "<br />";
     html += "The type of jsonString is " + typeof(jsonString) + "<br />";

     // Convert JSON string back to an object
     var arr_obj = toObject(jsonString);
     html += "The type of arr_obj is " + typeof(arr_obj);
     document.getElementById('content_div').innerHTML = html;

     // Encode object as JSON string
     function toJSON(obj) { 
       return gadgets.json.stringify(obj); 
     }

     // Convert JSON string into an object
     function toObject(str) {
       return gadgets.json.parse(str);
    }
    </script>
  ]]>
  </Content>
</Module>

이 가젯을 출력한 결과는 다음과 같습니다.

The JSON string is Touki","Rowan","Trevor
The type of jsonString is string
The type of arr_obj is object

인증 유형 설정

가젯 API는 다음 인증 유형을 지원합니다.

  • gadgets.io.AuthorizationType.OAUTH(컨테이너가 OAuth 프로토콜을 사용)
  • gadgets.io.AuthorizationType.SIGNED(컨테이너가 요청에 서명)
  • gadgets.io.AuthorizationType.NONE(기본값)

이러한 메서드를 사용하는 방법은 컨테이너에 따라 다릅니다. 여기에 orkut에만 해당하는 서명된 인증 유형을 사용하는 를 하나 제시합니다. 가젯에서의 OAuth 사용에 대한 논의는 OAuth 가젯 작성을 참조하시기 바랍니다.

메서드

makeRequest()를 사용하면 HTTP GET 및 POST 메서드 중에 선택할 수 있습니다.

GET

보통 GET을 사용하여 웹사이트에서 정보를 검색합니다. GET은 makeRequest()의 기본 모드지만 다음과 같이 명시적으로 GET 요청을 수행할 수 있습니다.

function makeGETRequest(url) {
   var params = {};
   params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.GET;
   gadgets.io.makeRequest(url, response, params); 
};
function response(obj) {
   alert(obj.text); 
};
makeGETRequest("http://example.com"); 

GET 요청에서 매개변수를 서버로 전달하려면 요청할 때 매개변수를 쿼리문자열에 추가하기만 하면 됩니다.

makeGETRequest("http://example.com?param1=12345&param2=hello"); 

POST

POST 요청은 보통 레코드를 수정 또는 삭제할 의도로 데이터를 서버에 전달하는 데 사용됩니다. GET 요청에서 보통 할 수 있는 것보다 POST 요청에서 더 많은 양의 데이터를 전달할 수 있습니다.

POST는 다음과 같은 코드를 사용하여 수행할 수 있습니다.

function makePOSTRequest(url, postdata) {
   var params = {};
   postdata = gadgets.io.encodeValues(postdata);
   params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.POST;
   params[gadgets.io.RequestParameters.POST_DATA]= postdata;
   gadgets.io.makeRequest(url, response, params); 
};
function response(obj) {
   output(obj.text); 
};
var data = {   data1 : "test",   data2 : 123456 }; 
makePOSTRequest("http://example.com", data); 

이 요청에 대해 opt_params에서 METHOD를 지정하는 것과 더불어 키 gadgets.io.RequestParameters.POST_DATA에서도 매개변수를 지정해야 합니다. POST에 대한 기본 인코딩은 POST_DATA 매개변수에 대한 값이 앰퍼샌드(&)와 결합된 일련의 URL 인코딩된 키-값 쌍이어야 함을 의미하는 application/x-www-form-urlencoded입니다. 데이터 개체를 이 형식으로 더 쉽게 변환하기 위해 gadgets.io.encodeValues 함수가 제공됩니다. encodeValues는 자바스크립트 개체를 받아들이고 POST_DATA 매개변수에 적절한 인코딩된 문자열을 반환합니다.

예를 들어 다음을 실행하면

var data = {   data1 : "test",   data2 : 123456 };  gadgets.io.encodeValues(data); 

다음 문자열이 만들어집니다.

data1=test&data2=123456 

이 문자열은 gadgets.io.RequestParameters.POST_DATA의 값으로서 직접 전달될 수 있습니다.

캐시 새로 고침

한 시간에 두 번 이상 업데이트되는 콘텐츠(예: 피드 데이터)를 가져오기 위해 makeRequest()를 사용한다면 최신 업데이트를 얻지 못할 것입니다. 왜냐하면 가젯이 더 빨리 실행되도록 하기 위해 결과가 캐시되기 때문입니다. 가젯에 최신 데이터가 포함되게 하려면 캐시를 무시하고 지정한 간격 내에서 새로고침이 발생하도록 하기 위해 refreshInterval 매개변수를 사용할 수 있습니다. 즉, 캐시가 X초 마다 새로 고쳐집니다. 여기에서 X = refreshInterval입니다.

makeRequest에 대한 호출은 기본적으로 캐시됩니다. 아래 예에서는 wrapper 함수가 동일한 매개변수를 makeRequest 호출로 사용하지만 refreshInterval이라는 다른 매개변수를 허용합니다. 이 매개변수를 사용하면 캐시 기간을 지정할 수 있습니다.

function makeCachedRequest(url, callback, params, refreshInterval) {
  var ts = new Date().getTime();
  var sep = "?";
  if (refreshInterval && refreshInterval > 0) {
    ts = Math.floor(ts / (refreshInterval * 1000));
  }
  if (url.indexOf("?") > -1) {
    sep = "&";
  }
  url = [ url, sep, "nocache=", ts ].join("");
  gadgets.io.makeRequest(url, response, params);
}

캐싱은 유용한 목적에 사용할 수 있지만 캐시를 너무 자주 새로 고쳐서 성능을 저하시키지 않도록 조심해야 합니다. 캐싱을 사용하면 데이터를 더 빨리 가져올 수 있으며 원격 콘텐츠를 호스팅하는 제3자 서버의 로드를 줄이기도 합니다. 따라서 캐시를 완전히 사용 중지(refreshInterval: 0을 사용하면 완전히 사용 중지됨)하지는 말아야 합니다. 가젯에 하루에 수백만 건의 페이지 뷰가 발생하여 서버에 수백만 건의 요청을 보내는 경우 캐시를 해제하면 가젯의 성능에 악영향을 줄 수 있을 뿐만 아니라 가젯에 데이터를 제공하는 서버에 과부하를 줄 수도 있습니다.

콘텐츠는 기본적으로 매시간 새로 고쳐지므로 간격을 한 시간 이내로 지정하는 것이 좋습니다. refreshInterval의 권장 범위는 60 - 3600 사이입니다.

맨위로