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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15617 -->
<!-- Reviewed: no -->
<sect1 id="zend.gdata.health">
    <title>Verwenden von Google Health</title>
    <para>
        Die Google Health Data API 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 XML 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 APIs hat jede der Google Health Feeds ein begrenztes Set von HTTP 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 API.
    </para>
    <sect2 id="zend.gdata.health.connect">
        <title>Zum Health Service verbinden</title>
        <para>
            Die Google Health API basiert, wie alle Google Data APIs, auf dem Atom Publishing
            Protokoll (APP), einem XML basierenden Format für die Verwaltung von Web-basierenden
            Ressourcen. Verkehr zwischen einem Client und dem Google Health Servern findet über HTTP
            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 HTTP 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 API 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 API
                        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 API 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 API 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 API.
            </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 HTTP 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 APIs, 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 mit gesetztem <code>permission=1</code> Parameter angefragt wurde. 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 API verwendet um ein Profil zu empfangen, werden speziell
                konstruierte Anfrage URLs 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 URL 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
                    <code>getHealthProfileFeed()</code> 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 <code>setDigest("true")</code> verwendet werden alle CCR Daten des
                    Benutzers in einem einzelnen Atom <code>&lt;entry&gt;</code> zurückgegeben.
                </para>
                <para>
                    Dem <code>setCategory()</code> 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
                    <code>setCategory("medication", "Lipitor")</code>. 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 API 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 <code>digest=true</code> dazu das alle CCR Elemente (die dieser
                Abfrage entsprechen) in einen einzelnen Atom <code>&lt;entry&gt;</code>
                zusammengefügt werden.
            </para>
            <para>
                Um die kompletten CCR Informationen von einem Eintrag zu erhalten, muß ein Aufruf
                zur <code>getCcr()</code> 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 <code>getCcr()</code> 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
                <code>getCATEGORYNAME()</code>, wobei <code>CATEGORYNAME</code> 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 <code>&lt;content&gt;</code> und der Name im
            <code>&lt;title&gt;</code> 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
                <code>getHealthProfileListFeed()</code> 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
                <code>setProfileID()</code> mit der Profil ID als Argument aufgerufen. Das begrenzt
                die weiteren API 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 XHTML 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 <code>sendHealthNotice()</code> 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>