repo_zf1/documentation/manual/de/module_specs/Zend_Gdata_Health.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.gdata.health">
    <title>Verwenden von Google Health</title>

    <para>
        Die Google Health Data <acronym>API</acronym> wurde entwickelt um es Entwicklern zu erlauben
        die folgenden 2 Dinge zu tun:

        <itemizedlist>
            <listitem>
                <para>
                    Das Google Gesundheitsprofil eines Benutzers lesen oder nach medizinischen
                    Einträgen zu suchen die einem speziellen Kriterium entsprechen und dann die
                    Ergebnisse zu verwenden um personalisierte Funktionalitäten basierend auf diesen
                    Daten anzubieten.
                </para>
            </listitem>

            <listitem>
                <para>
                    Neue Medizinische Daten zu einem Benutzerprofil hinzuzufügen indem CCR Daten
                    eingefügt werden wenn eine Notiz an ein Benutzerprofil gesendet wird. Es ist zu
                    beachten das die CCR Daten als <acronym>XML</acronym> Blob im &lt;atom&gt;
                    Eintrag gespeichert werden. Die Bibliothek bietet keine direkten
                    Zugriffsmethoden zu dem Objektmodell an aber es hat Helfer für das extrahieren
                    von speziellen Feldern.
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        Es gibt drei Hauptfeeds, die alle eine Authentifikation benötigen. Anders als andere Google
        Data <acronym>API</acronym>s hat jede der Google Health Feeds ein begrenztes Set von
        <acronym>HTTP</acronym> Anweisungen die auf Ihm ausgeführt werden können, abhängig von der
        Authentifizierungsmethode die man verwendet (ClientLogin oder AuthSub/OAuth). Für eine Liste
        von gestatteten Anweisungen siehe <ulink
            url="http://code.google.com/apis/health/reference.html#Authentication">http://code.google.com/apis/health/reference.html#Authentication</ulink>.

        <itemizedlist>
            <listitem>
                <para>
                    <firstterm>Profil Feed</firstterm> verwende den Profilfeed um das
                    Gesundheitsprofil eines Benutzers nach speziellen Informationen zu durchsuchen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <firstterm>Registrierungs Feed</firstterm>
                    verwende den Registrierungsfeed um neue CCR Daten in ein Profil einzupflegen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <firstterm>Profil Listen Feed</firstterm> der Profil Listen Feed sollte
                    verwendet werden um festzustellen mit welchem Gesundheitsprofil eines Benutzer
                    interagiert werden soll. Dieser Feed ist nur vorhanden wenn man ClientLogin
                    verwendet.
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        Siehe <ulink
            url="http://code.google.com/apis/health/">http://code.google.com/apis/health</ulink> für
        weitere Informationen über die Google Health <acronym>API</acronym>.
    </para>

    <sect2 id="zend.gdata.health.connect">
        <title>Zum Health Service verbinden</title>

        <para>
            Die Google Health <acronym>API</acronym> basiert, wie alle Google Data
            <acronym>API</acronym>s, auf dem Atom Publishing Protokoll (APP), einem
            <acronym>XML</acronym> basierenden Format für die Verwaltung von Web-basierenden
            Ressourcen. Verkehr zwischen einem Client und dem Google Health Servern findet über
            <acronym>HTTP</acronym> statt und erlaubt authentifizierte Verbindungen.
        </para>

        <para>
            Bevor eine Transaktion stattfinden kann, muß eine Verbindung erstellt werden. Das
            Erstellen einer Verbindung zu den Health Servern beinhaltet zwei Schritte: Erstellung
            eines <acronym>HTTP</acronym> Clients und diesen Client an eine
            <classname>Zend_Gdata_Health</classname> Instanz binden.
        </para>

        <sect3 id="zend.gdata.health.connect.authentication">
            <title>Authentifikation</title>

            <para>
                Die Google Health <acronym>API</acronym> erlaubt den programmtechnischen Zugriff auf
                das Gesundheitsprofil eines Benutzer. Es gibt drei Authentifizierungsschemata die
                von Google Health unterstützt werden:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <firstterm>ClientLogin</firstterm>
                        bietet direkte Benutzername/Passwort Authentifikation zu den Health Servern.
                        Da diese Methoden erwarten das Benutzer Ihr Passwort der Anwendung angeben
                        müssen, wird dieses Authentifizierungsschema nur für
                        installierte/Desktopanwendungen empfohlen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <firstterm>AuthSub</firstterm>
                        erlaubt es einen Benutzer seine privaten Daten zu teilen. Das bietet das
                        selbe Level der bequemlichkeit wir ClientLogin, aber ohne das
                        Sicherheitsrisiko, was es zu einer idealen Wahl für Web-basierende
                        Anwendungen macht. Für Google Health muß AuthSub in einem registrierten und
                        sicheren Modus verwendet werden -- was bedeutet das alle Anfragen zur
                        <acronym>API</acronym> digital signiert werden müssen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <firstterm>OAuth</firstterm>
                        ist eine alternative zu AuthSub. Auch wenn dieses Authentifizierungschema
                        nicht in diesem Dokument diskutiert wird, können weitere Informationen hier
                        gefunden werden: <ulink
                            url="http://code.google.com/apis/health/developers_guide_protocol.html#OAuth">Health
                            Data <acronym>API</acronym> Developer's Guide</ulink>.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Siehe
                <ulink url="http://code.google.com/apis/gdata/auth.html">Authentication Overview in
                    the Google Data <acronym>API</acronym> documentation</ulink> für weitere
                Informationen über jede Authentifizierungsmethode.
            </para>
        </sect3>

        <sect3 id="zend.gdata.health.connect.service">
            <title>Erstellen einer Health Service Instanz</title>

            <para>
                Um mit Google Health zu interagieren, bietet die Client Bibliothek die Serviceklasse
                <classname>Zend_Gdata_Health</classname>. Diese Klasse bietet ein übliches Interface
                zu den Google Data und Atom Publishing Protokoll Modellen und hilft bei der
                Durchführung von Anfragen von und zur Health <acronym>API</acronym>.
            </para>

            <para>
                Sobald man sich für ein Authentifizierungsschema entschieden hat, ist der nächste
                Schritt die Erstellung einer Instanz von <classname>Zend_Gdata_Health</classname>.
                Dieser Klasse sollte eine Instanz von <classname>Zend_Gdata_HttpClient</classname>
                übergeben werden. Diese bietet ein Interface für- AuthSub/OAuth und ClientLogin um
                einen speziell authentifizierten <acronym>HTTP</acronym> Client zu erstellen.
            </para>

            <para>
                Um mit dem H9 des Entwicklers (/h9) statt Google Health (/health) nimmt der
                Konstruktor von <classname>Zend_Gdata_Health</classname> ein optionales drittes
                Argument mit dem man den H9 Service Name 'weaver' spezifizieren kann.
            </para>

            <para>
                Das folgende Beispiel zeigt wie eine Health Service Klasse bei Verwendung der
                ClientLogin Authentifizierung erstellt wird:
            </para>

            <programlisting language="php"><![CDATA[
// Parameter für die ClientLogin Authentifikation
$healthServiceName = Zend_Gdata_Health::HEALTH_SERVICE_NAME;
//$h9ServiceName = Zend_Gdata_Health::H9_SANDBOX_SERVICE_NAME;
$user = "user@gmail.com";
$pass = "pa$$w0rd";

// Erstellt einen authentifizierten HTTP Client
$client = Zend_Gdata_ClientLogin::getHttpClient($user,
                                                $pass,
                                                $healthServiceName);

// Erstellt eine Instanz des Health Services
$service = new Zend_Gdata_Health($client);
]]></programlisting>

            <para>
                Ein Health Service der AuthSub verwendet kann ähnlich erstellt werden, im einem
                etwas längeren Aussehen. AuthSub ist das empfohlene Interface um mit Google Health
                zu kommunizieren weil jeder Token direkt zu einem speziellen Profil im Account des
                Benutzers verlinkt wird. Anders als andere Google Data <acronym>API</acronym>s, ist
                es notwendig das alle Anfragen von der eigenen Anwendung digital signiert werden.
            </para>

            <programlisting language="php"><![CDATA[
/*
 * Empfängt die aktuelle URL damit der AuthSub Server weiß wohin er den
 * Benutzer routen soll nachdem die Authentifizierung komplett ist.
 */
function getCurrentUrl() {
    $phpRequestUri = htmlentities(substr($_SERVER['REQUEST_URI'],
                                         0,
                                         strcspn($_SERVER['REQUEST_URI'],
                                                 "\n\r")),
                                  ENT_QUOTES);

    if (isset($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) == 'on') {
        $protocol = 'https://';
    } else {
        $protocol = 'http://';
    }
    $host = $_SERVER['HTTP_HOST'];
    if ($_SERVER['SERVER_PORT'] != '' &&
       (($protocol == 'http://' && $_SERVER['SERVER_PORT'] != '80') ||
       ($protocol == 'https://' && $_SERVER['SERVER_PORT'] != '443'))) {
        $port = ':' . $_SERVER['SERVER_PORT'];
    } else {
        $port = '';
    }
    return $protocol . $host . $port . $phpRequestUri;
}

/*
 * Leitet einen Benutzer zu AuthSub um wenn er keinen gültigen Session Token
 * hat. Wenn er von AuthSub mit einem einmal-zu-verwendenden Token zurückkommt,
 * wird ein neuer HTTP Client initialisiert und der Token mit eine langlebigen
 * Sessiontoken getauscht.
 */
function setupClient($singleUseToken = null) {
    $client = null;

    // Einen neuen AuthSub Token holen?
    if (!$singleUseToken) {
        $next = getCurrentUrl();
        $scope = 'https://www.google.com/health/feeds';
        $authSubHandler = 'https://www.google.com/health/authsub';
        $secure = 1;
        $session = 1;
        $authSubURL =  Zend_Gdata_AuthSub::getAuthSubTokenUri($next,
                                                              $scope,
                                                              $secure,
                                                              $session,
                                                              $authSubHandler);

         // 1 - Erlaubt es Notizen zu schicken und das Lesen von Profildaten
        $permission = 1;
        $authSubURL .= '&permission=' . $permission;

        echo '<a href="' . $authSubURL . '">Dein Google Health Account</a>';
    } else {
        $client = new Zend_Gdata_HttpClient();

        // Setzen des privaten Schlüssels mit dem nachfolgende Anfragen
        // signiert werden
        $client->setAuthSubPrivateKeyFile('/path/to/your/rsa_private_key.pem',
                                          null,
                                          true);

        $sessionToken =
            Zend_Gdata_AuthSub::getAuthSubSessionToken(trim($singleUseToken),
                                                       $client);

        // Setzt den langlebigen Sessiontoken für nachfolgende Anfragen
        $client->setAuthSubToken($sessionToken);
    }
    return $client;
}

// -> Skriptausführung beginnt hier <-

session_start();

$client = setupClient(@$_GET['token']);

// Erstellt eine Instanz des Health Services
$userH9Sandbox = false;
$healthService = new Zend_Gdata_Health($client,
                                       'googleInc-MyTestAppName-v1.0',
                                       $userH9Sandbox);
]]></programlisting>

            <para>
                Achtung: der Rest dieses Dokument wird annehmen das man AuthSub für die
                Authentifikation verwendet.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.health.profilefeed">
        <title>Profil Feed</title>

        <para>
            Um den Profil Feed des Benutzers abzufragen, muß man sicherstellen das der initiale
            AuthSub Token angefragt wird wobei der <property>permission</property> Parameter auf
            <emphasis>1</emphasis> gesetzt ist. Der Prozess des extrahierens von Daten aus dem
            Profil benötigt zwei Schritte. Das Senden einer Anfrage und dem durchlaufen des
            resultierenden Feeds.
        </para>

        <sect3 id="zend.gdata.health.profilefeed.query">
            <title>Eine strukturierte Anfrage senden</title>

            <para>
                Man kann strukturierte Anfragen senden um spezielle Einträge von einem
                Benutzerprofil zu erhalten.
            </para>

            <para>
                Wenn man die Health <acronym>API</acronym> verwendet um ein Profil zu empfangen,
                werden speziell konstruierte Anfrage <acronym>URL</acronym>s verwendet um zu
                beschreiben welche (CCR) Daten zurückgegeben werden sollen. Die Klasse
                <classname>Zend_Gdata_Health_Query</classname> hilft dabei diese Aufgabe zu
                vereinfachen indem automatisch eine Abfrage <acronym>URL</acronym> erstellt wird
                basierend auf den Parametern die man gesetzt hat.
            </para>

            <sect4 id="zend.gdata.health.profilefeed.query.construct">
                <title>Den Feed abfragen</title>

                <para>
                    Um eine Abfrage eines Profil Feeds durchzuführen, muß eine neue Instanz von
                    <classname>Zend_Gdata_Health_Query</classname> erzeugt und die
                    <methodname>getHealthProfileFeed()</methodname> Methode des Services aufgerufen
                    werden:
                </para>

                <programlisting language="php"><![CDATA[
$healthService = new Zend_Gdata_Health($client);

// Beispielabfrage für die besten 10 Medikationen mit jeweils 2 Elementen
$query = new Zend_Gdata_Health_Query();
$query->setDigest("true");
$query->setGrouped("true");
$query->setMaxResultsGroup(10);
$query->setMaxResultsInGroup(2);
$query->setCategory("medication");

$profileFeed = $healthService->getHealthProfileFeed($query);
]]></programlisting>

                <para>
                    Wenn man <methodname>setDigest("true")</methodname> verwendet werden alle CCR
                    Daten des Benutzers in einem einzelnen Atom <emphasis>&lt;entry&gt;</emphasis>
                    zurückgegeben.
                </para>

                <para>
                    Dem <methodname>setCategory()</methodname> Helfer kann ein zusätzlicher
                    Parameter übergeben werden um spezifischere CCR Informationen zurückzuerhalten.
                    Um zum Beispiel nur die Medikation Lipitor zurückzugeben verwendet man
                    <methodname>setCategory("medication", "Lipitor")</methodname>. Die selbe Methode
                    kann bei anderen Kategorien wie Konditionen, Allergien, Labor Ergebnisse, usw.
                    angewendet werden.
                </para>

                <para>
                    Eine komplette Liste der unterstützten Abfrageparameter ist im <ulink
                        url="http://code.google.com/apis/health/reference.html#Parameters">Kapitel
                        der Abfrageparameter</ulink> des Health <acronym>API</acronym> Referenz
                    Guides vorhanden.
                </para>
            </sect4>
        </sect3>

        <sect3 id="zend.gdata.health.profilefeed.iterate">
            <title>Durch die Profil Einträge iterieren</title>

            <para>
                Jeder Google Health Eintrag enthält CCR Daten, trotzem führt die Verwendung des
                Abfrageparameters <property>digest</property> mit <constant>TRUE</constant> dazu
                dass alle CCR Elemente (die dieser Abfrage entsprechen) in einen einzelnen Atom
                <emphasis>&lt;entry&gt;</emphasis> zusammengefügt werden.
            </para>

            <para>
                Um die kompletten CCR Informationen von einem Eintrag zu erhalten, muß ein Aufruf
                zur <methodname>getCcr()</methodname> Methode der
                <classname>Zend_Gdata_Health_ProfileEntry</classname> Klasse durchgeführt werden.
                Das gibt ein <classname>Zend_Gdata_Health_Extension_CCR</classname> zurück:
            </para>

            <programlisting language="php"><![CDATA[
$entries = $profileFeed->getEntries();
foreach ($entries as $entry) {
    $medications = $entry->getCcr()->getMedications();
    //$conditions = $entry->getCcr()->getConditions();
    //$immunizations = $entry->getCcr()->getImmunizations();

    // Das CCR XML ausgeben (das werden nur die Medikationen des Eintrags sein)
    foreach ($medications as $med) {
        $xmlStr = $med->ownerDocument->saveXML($med);
        echo "<pre>" . $xmlStr . "</pre>";
    }
}
]]></programlisting>

            <para>
                Hier wird die <methodname>getCcr()</methodname> Methode in Verbindung mit einem
                magischen Helfer verwendet um nur die Medikationsdaten aufzureißen und aus den CCR
                des Eintrags zu extrahieren. Der hierbei erwähnte magische Helfer nimmt das Formular
                <methodname>getCATEGORYNAME()</methodname>, wobei <constant>CATEGORYNAME</constant>
                eine unterstützte Kategorie von Google Health ist. Für mögliche Kategorien kann in
                den <ulink url="http://code.google.com/apis/health/reference.html#CatQueries">Google
                    Health Referenz Guide</ulink> gesehen werden.
            </para>

            <para>
                Um effizienter zu sein, können auch Kategorie Abfragen verwendet werden um nur die
                notwendigen CCRs von den Google Health Servern zu erhalten. Dann muß durch diese
                Ergebnisse iteriert werden:
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Health_Query();
$query->setDigest("true");
$query->setCategory("condition");
$profileFeed = $healthService->getHealthProfileFeed($query);

// Da die Abfrage digest=true enthält, wird nur der Atom Eintrag zurückgegeben
$entry = $profileFeed->entry[0];
$conditions = $entry->getCcr()->getConditions();

// Die CCR Daten ausgeben (das sind nur die Konditionen des Profils)
foreach ($conditions as $cond) {
    $xmlStr = $cond->ownerDocument->saveXML($cond);
    echo "<pre>" . $xmlStr . "</pre>";
}
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.health.profilelist">
        <title>Profil Listen Feed</title>

        <para>
            Beachte: Dieser Feed ist nur vorhanden wenn man ClientLogin verwendet
        </para>

        <para>
            Da ClientLogin bei jedem seiner Feeds eine Profil ID benötigt, sollten Anwendungen
            diesen Feed als erstes abfragen um die richtigen Profile auszuwählen. Der Profil Listen
            Feed gibt Atom Einträge zurück die jedem Profil im Benutzeraccount von Google Health
            entsprechen. Die ProfilID wird im Atom <emphasis>&lt;content&gt;</emphasis> und der Name
            im <emphasis>&lt;title&gt;</emphasis> Element zurückgegeben.
        </para>

        <sect3 id="zend.gdata.health.profilelist.query">
            <title>Den Feed abfragen</title>

            <para>
                Um eine Abfrage gegen den Profil Listen Feed durchzuführen muß die
                <methodname>getHealthProfileListFeed()</methodname> Methode des Services aufgerufen
                werden:
            </para>

            <programlisting language="php"><![CDATA[
$client = Zend_Gdata_ClientLogin::getHttpClient('user@gmail.com',
                                                'pa$$word',
                                                'health');
$healthService = new Zend_Gdata_Health($client);
$feed = $healthService->getHealthProfileListFeed();

// Jeden Namen und jede ID des Profils ausgeben
$entries = $feed->getEntries();
foreach ($entries as $entry) {
    echo '<p>Profil Name: ' . $entry->getProfileName() . '<br>';
    echo 'Profil ID: ' . $entry->getProfileID() . '</p>';
}
]]></programlisting>

            <para>
                Sobald man sich entschieden hat welches Profil verwendet werden soll, wird
                <methodname>setProfileID()</methodname> mit der Profil ID als Argument aufgerufen.
                Das begrenzt die weiteren <acronym>API</acronym> Abfragen auf genau das betreffende
                Profil:
            </para>

            <programlisting language="php"><![CDATA[
// Verwende das erste Profil
$profileID = $feed->entry[0]->getProfileID();
$healthService->setProfileID($profileID);

$profileFeed = $healthService->getHealthProfileFeed();

$profileID = $healthService->getProfileID();
echo '<p><b>Abgefragte Profil ID</b>: ' . $profileID . '</p>';
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.health.notice">
        <title>Notizen an des Register Feed versenden</title>

        <para>
            Individuelle Antworten zum registrierten Feed sind als Notizen bekannt. Notizen werden
            von Dritt-Anwendungen gesendet um den Benutzer über ein neues Event zu informieren. Mit
            AuthSub/OAuth, sind Notizen einfach etwas womit die eigene Anwendung neue CCR
            Informationen zu einem Benutzerprofil hinzufügen kann. Notizen können reinen Text
            enthalten (inklusive einiger <acronym>XHTML</acronym> Elemente), ein CCR Dokument oder
            beides. Als Beispiel können Notizen gesendet werden um Benutzer daran zu erinnern das
            Sie spezielle Rezepte nehmen sollen, oder sie können Laborergebnisse im CCR Format
            enthalten.
        </para>

        <sect3 id="zend.gdata.health.notice.send">
            <title>Senden einer Notiz</title>

            <para>
                Notizen können durch das Verwenden der <methodname>sendHealthNotice()</methodname>
                Methode des Health Services gesendet werden:
            </para>

            <programlisting language="php"><![CDATA[
$healthService = new Zend_Gdata_Health($client);

$subject = "Der Titel der Notiz ist hier";
$body = "Der Notizinhalt kann einige <b>html</b> Elemente enthalten";
$ccr = '<ContinuityOfCareRecord xmlns="urn:astm-org:CCR">
  <Body>
   <Problems>
    <Problem>
      <DateTime>
        <Type><Text>Start Datum</Text></Type>
        <ExactDateTime>2007-04-04T07:00:00Z</ExactDateTime>
      </DateTime>
      <Description>
        <Text>Medikament gegen Aorta Verengung</Text>
        <Code>
          <Value>410.10</Value>
          <CodingSystem>ICD9</CodingSystem>
          <Version>2004</Version>
        </Code>
      </Description>
      <Status><Text>Aktiv</Text></Status>
    </Problem>
  </Problems>
  </Body>
</ContinuityOfCareRecord>';

$responseEntry = $healthService->sendHealthNotice($subject,
                                                  $body,
                                                  "html",
                                                  $ccr);
]]></programlisting>
        </sect3>
    </sect2>
</sect1>