تكوين مصادر البيانات لتطبيق Tomcat أو JBoss أو Java SE في Azure App Service

توضح هذه المقالة كيفية تكوين مصادر البيانات في تطبيق Java SE أو Tomcat أو JBoss في App Service.

تقوم Azure App Service بتشغيل تطبيقات ويب Java على خدمة مدارة بالكامل في ثلاثة متغيرات:

• Java SE - يمكنه تشغيل تطبيق تم نشره كحزمة JAR تحتوي على خادم مضمن (مثل Spring Boot أو Dropwizard أو Quarkus أو تطبيق مع خادم Tomcat أو Jetty مضمن).
• Tomcat - يمكن لخادم Tomcat المضمن تشغيل تطبيق تم نشره كحزمة WAR.
• JBoss EAP - مدعوم لتطبيقات Linux في مستويات التسعير Premium v3 و Isolated v2 فقط. يمكن لخادم JBoss EAP المضمن تشغيل تطبيق تم نشره كحزمة WAR أو EAR.

إشعار

بالنسبة لتطبيقات Spring، نوصي باستخدام Azure Spring Apps. ومع ذلك، لا يزال بإمكانك استخدام Azure App Service كوجهة. راجع إرشادات وجهة حمل عمل Java للحصول على المشورة.

تكوين مصدر البيانات

للاتصال بمصادر البيانات في تطبيقات Spring Boot، نقترح إنشاء سلاسل اتصال وتضمينها في ملف application.properties الموجود لديك.

1. في مقطع "التكوين" من صفحة App Service، عيّن اسماً للسلسلة، والصق سلسلة اتصال JDBC في حقل القيمة، ثم عيّن النوع على "مخصص". يمكنك اختيارياً تعيين سلسلة الاتصال هذه كإعداد فتحة.

   يمكن لتطبيقنا الوصول إلى سلسلة الاتصال هذه باعتبارها متغير بيئة بالاسم CUSTOMCONNSTR_<your-string-name>. على سبيل المثال، CUSTOMCONNSTR_exampledb

2. في ملف application.properties لديك، قم بالإشارة إلى سلسلة الاتصال هذه باستخدام اسم متغير البيئة. على سبيل المثال، سنستخدم التعليمات البرمجية التالية:

   app.datasource.url=${CUSTOMCONNSTR_exampledb}
   

لمزيد من المعلومات، راجع وثائق Spring Boot حول الوصول إلى البيانات والتكوينات الخارجية.

تلميح

بشكل افتراضي، يمكن لحاويات Linux Tomcat تكوين مصادر البيانات المشتركة تلقائيا لك في خادم Tomcat. الشيء الوحيد الذي عليك القيام به هو إضافة إعداد تطبيق يحتوي على سلسلة الاتصال JDBC صالح إلى قاعدة بيانات Oracle أو SQL Server أو PostgreSQL أو MySQL (بما في ذلك بيانات اعتماد الاتصال)، وتضيف App Service تلقائيا قاعدة البيانات المشتركة cooresponding إلى /usr/local/tomcat/conf/context.xml لك، باستخدام برنامج تشغيل مناسب متوفر في الحاوية. للحصول على سيناريو شامل باستخدام هذا الأسلوب، راجع البرنامج التعليمي: إنشاء تطبيق ويب Tomcat باستخدام Azure App Service على Linux وMySQL.

تنطبق هذه الإرشادات على جميع اتصالات قاعدة البيانات. تحتاج إلى تعبئة العناصر النائبة باسم فئة برنامج تشغيل قاعدة البيانات المختارة وملف JAR. يتوفر جدول بأسماء الفئات و تنزيلات برامج التشغيل لقواعد البيانات الشائعة.

قاعدة البيانات	اسم فئة برنامج التشغيل	برنامج تشغيل JDBC
PostgreSQL	org.postgresql.Driver	تنزيل
MySQL	com.mysql.jdbc.Driver	تنزيل (حدد "مستقل عن النظام الأساسي")
SQL Server	com.microsoft.sqlserver.jdbc.SQLServerDriver	تنزيل

لتكوين Tomcat لاستخدام Java Database Connectivity (JDBC) أو Java Persistence API ‏(JPA)، قم أولاً بتخصيص متغير البيئة CATALINA_OPTS الذي تتم قراءته بواسطة Tomcat عند بدء التشغيل. يمكنك تعيين هذه القيم من خلال إعداد تطبيق في وظيفة Maven الإضافية لـ App Service:

<appSettings>
    <property>
        <name>CATALINA_OPTS</name>
        <value>"$CATALINA_OPTS -Ddbuser=${DBUSER} -Ddbpassword=${DBPASSWORD} -DconnURL=${CONNURL}"</value>
    </property>
</appSettings>

أو يمكنك تعيين متغيرات البيئة في صفحةالتكوين>إعدادات التطبيق في مدخل Azure.

بعد ذلك، حدد ما إذا كان يجب توفير مصدر البيانات لتطبيق واحد أو لجميع التطبيقات التي يتم تشغيلها على Tomcat servlet.

مصادر البيانات على مستوى التطبيق

1. أنشئ ملف context.xml في دليل META-INF/ لمشروعك. إنشاء الدليل META-INF/ إذا لم يكن موجودا.

2. في context.xml، أضف عنصر Context لربط مصدر البيانات بعنوان JNDI. استبدل العنصر النائب driverClassName باسم فئة برنامج التشغيل من الجدول بالأعلى.

   <Context>
       <Resource
           name="jdbc/dbconnection"
           type="javax.sql.DataSource"
           url="${connURL}"
           driverClassName="<insert your driver class name>"
           username="${dbuser}"
           password="${dbpassword}"
       />
   </Context>
   

3. حدّث web.xml لتطبيقك حتى تتمكن من استخدام مصدر البيانات في تطبيقك.

   <resource-env-ref>
       <resource-env-ref-name>jdbc/dbconnection</resource-env-ref-name>
       <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
   </resource-env-ref>
   

الموارد المشتركة على مستوى الخادم

Linux

تتطلب إضافة مصدر بيانات مشترك على مستوى الخادم تحرير server.xml Tomcat. الطريقة الأكثر موثوقية للقيام بذلك هي كما يلي:

1. تحميل برنامج نصي لبدء التشغيل وتعيين المسار إلى البرنامج النصي في أمر بدء تشغيل التكوين>. يمكنك تحميل البرنامج النصي لبدء التشغيل باستخدام FTP.

يقوم البرنامج النصي لبدء التشغيل بتحويل xsl إلى ملف server.xml وإخراج ملف xml الناتج إلى /usr/local/tomcat/conf/server.xml. يجب أن يقوم البرنامج النصي لبدء التشغيل بتثبيت libxslt عبر apk. يمكن تحميل ملف xsl والبرنامج النصي لبدء التشغيل عبر FTP. فيما يلي مثال للبرنامج النصي لبدء التشغيل.

# Install libxslt. Also copy the transform file to /home/tomcat/conf/
apk add --update libxslt

# Usage: xsltproc --output output.xml style.xsl input.xml
xsltproc --output /home/tomcat/conf/server.xml /home/tomcat/conf/transform.xsl /usr/local/tomcat/conf/server.xml

يضيف ملف XSL المثال التالي عقدة موصل جديدة إلى server.xml Tomcat.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="@* | node()" name="Copy">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="@* | node()" mode="insertConnector">
    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                 contains(., '&lt;Connector') and
                                 (contains(., 'scheme=&quot;https&quot;') or
                                  contains(., &quot;scheme='https'&quot;))]">
    <xsl:value-of select="." disable-output-escaping="yes" />
  </xsl:template>

  <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                   comment()[contains(., '&lt;Connector') and
                                             (contains(., 'scheme=&quot;https&quot;') or
                                              contains(., &quot;scheme='https'&quot;))]
                                  )]
                      ">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()" mode="insertConnector" />
    </xsl:copy>
  </xsl:template>

  <!-- Add the new connector after the last existing Connnector if there's one -->
  <xsl:template match="Connector[last()]" mode="insertConnector">
    <xsl:call-template name="Copy" />

    <xsl:call-template name="AddConnector" />
  </xsl:template>

  <!-- ... or before the first Engine if there's no existing Connector -->
  <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                mode="insertConnector">
    <xsl:call-template name="AddConnector" />

    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template name="AddConnector">
    <!-- Add new line -->
    <xsl:text>&#xa;</xsl:text>
    <!-- This is the new connector -->
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
               maxThreads="150" scheme="https" secure="true" 
               keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
               clientAuth="false" sslProtocol="TLS" />
  </xsl:template>

</xsl:stylesheet>

إنهاء التكوين

وأخيراً، ضع ملفات JAR لبرنامج التشغيل في Tomcat classpath وأعد تشغيل App Service لديك.

1. تأكد من أن ملفات برنامج تشغيل JDBC متوفرة لمحمل فئة Tomcat عن طريق وضعها في الدليل /home/site/lib . في Cloud Shell، قم بتشغيل az webapp deploy --type=lib لكل برنامج تشغيل JAR:

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --path <jar-name>.jar

إذا كنت قد أنشئت مصدر بيانات على مستوى الخادم، فأعد تشغيل تطبيق App Service Linux. يقوم Tomcat بإعادة CATALINA_BASE /home/tomcat تعيين التكوين المحدث واستخدامه.

Windows

لا يمكنك تعديل تثبيت Tomcat مباشرة للتكوين على مستوى الخادم لأن موقع التثبيت للقراءة فقط. لإجراء تغييرات التكوين على مستوى الخادم على تثبيت Windows Tomcat، أبسط طريقة هي القيام بما يلي في بدء تشغيل التطبيق:

1. انسخ Tomcat إلى دليل محلي (%LOCAL_EXPANDED%) واستخدمه ك CATALINA_BASE (راجع وثائق Tomcat على هذا المتغير).
2. أضف مصادر البيانات المشتركة إلى %LOCAL_EXPANDED%\tomcat\conf\server.xml استخدام تحويل XSL.

إضافة ملف بدء التشغيل

إنشاء ملف باسم startup.cmd %HOME%\site\wwwroot الدليل. يتم تشغيل هذا الملف تلقائيا قبل بدء تشغيل خادم Tomcat. يجب أن يحتوي الملف على المحتوى التالي:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -File  %HOME%\site\configure.ps1

إضافة البرنامج النصي لتكوين PowerShell

بعد ذلك، أضف البرنامج النصي للتكوين المسمى configure.ps1 إلى دليل ٪HOME٪_\site مع التعليمات البرمجية التالية:

# Locations of xml and xsl files
$target_xml="$Env:LOCAL_EXPANDED\tomcat\conf\server.xml"
$target_xsl="$Env:HOME\site\server.xsl"

# Define the transform function
# Useful if transforming multiple files
function TransformXML{
    param ($xml, $xsl, $output)

    if (-not $xml -or -not $xsl -or -not $output)
    {
        return 0
    }

    Try
    {
        $xslt_settings = New-Object System.Xml.Xsl.XsltSettings;
        $XmlUrlResolver = New-Object System.Xml.XmlUrlResolver;
        $xslt_settings.EnableScript = 1;

        $xslt = New-Object System.Xml.Xsl.XslCompiledTransform;
        $xslt.Load($xsl,$xslt_settings,$XmlUrlResolver);
        $xslt.Transform($xml, $output);
    }

    Catch
    {
        $ErrorMessage = $_.Exception.Message
        $FailedItem = $_.Exception.ItemName
        echo  'Error'$ErrorMessage':'$FailedItem':' $_.Exception;
        return 0
    }
    return 1
}

# Start here

# Check for marker file indicating that config has already been done
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker"){
    return 0
}

# Delete previous Tomcat directory if it exists
# In case previous config isn't completed or a new config should be forcefully installed
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat"){
    Remove-Item "$Env:LOCAL_EXPANDED\tomcat" Recurse
}

md -Path "$Env:LOCAL_EXPANDED\tomcat"

# Copy Tomcat to local
# Using the environment variable $AZURE_TOMCAT90_HOME uses the 'default' version of Tomcat
New-Item "$Env:LOCAL_EXPANDED\tomcat" -ItemType Directory
Copy-Item -Path "$Env:AZURE_TOMCAT90_HOME\*" "$Env:LOCAL_EXPANDED\tomcat" -Recurse

# Perform the required customization of Tomcat
$success = TransformXML -xml $target_xml -xsl $target_xsl -output $target_xml

# Mark that the operation was a success if successful
if($success){
    New-Item -Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker" -ItemType File
}

يكمل PowerShell هذا الخطوات التالية:

1. تحقق مما إذا كانت نسخة Tomcat مخصصة موجودة بالفعل. إذا كان الأمر كذلك، يمكن أن ينتهي البرنامج النصي لبدء التشغيل هنا.
2. انسخ Tomcat محلياً.
3. أضف مصادر البيانات المشتركة إلى تكوين Tomcat المخصص باستخدام تحويل XSL.
4. وضِّح أنه تم إكمال التكوين بنجاح.

إضافة ملف تحويل XSL

من حالات الاستخدام الشائعة لتخصيص تثبيت Tomcat المضمن تعديل server.xmlملفات التكوين أو context.xmlأو web.xml Tomcat. يعدّل App Service هذه الملفات بالفعل لتوفير ميزات النظام الأساسي. لمتابعة استخدام هذه الميزات، من المهم الاحتفاظ بمحتوى هذه الملفات عند إجراء تغييرات عليها. لتحقيق ذلك، استخدم تحويل XSL (XSLT) .

أضف ملف تحويل XSL يسمى configure.ps1 إلى دليل ٪HOME٪_\site . يمكنك استخدام التعليمات البرمجية لتحويل XSL التالية لإضافة عقدة موصل جديدة إلى server.xml. يحافظ تحويل الهوية في البداية على المحتويات الأصلية لملف التكوين.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="yes"/>

    <!-- Identity transform: this ensures that the original contents of the file are included in the new file -->
    <!-- Ensure that your transform files include this block -->
    <xsl:template match="@* | node()" name="Copy">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()"/>
      </xsl:copy>
    </xsl:template>

    <xsl:template match="@* | node()" mode="insertConnector">
      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                   contains(., '&lt;Connector') and
                                   (contains(., 'scheme=&quot;https&quot;') or
                                    contains(., &quot;scheme='https'&quot;))]">
      <xsl:value-of select="." disable-output-escaping="yes" />
    </xsl:template>

    <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                     comment()[contains(., '&lt;Connector') and
                                               (contains(., 'scheme=&quot;https&quot;') or
                                                contains(., &quot;scheme='https'&quot;))]
                                    )]
                        ">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()" mode="insertConnector" />
      </xsl:copy>
    </xsl:template>

    <!-- Add the new connector after the last existing Connnector if there's one -->
    <xsl:template match="Connector[last()]" mode="insertConnector">
      <xsl:call-template name="Copy" />

      <xsl:call-template name="AddConnector" />
    </xsl:template>

    <!-- ... or before the first Engine if there's no existing Connector -->
    <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                  mode="insertConnector">
      <xsl:call-template name="AddConnector" />

      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template name="AddConnector">
      <!-- Add new line -->
      <xsl:text>&#xa;</xsl:text>
      <!-- This is the new connector -->
      <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
                 maxThreads="150" scheme="https" secure="true" 
                 keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
                 clientAuth="false" sslProtocol="TLS" />
    </xsl:template>

</xsl:stylesheet>

تعيين CATALINA_BASE إعداد التطبيق

يحتاج النظام الأساسي أيضاً إلى معرفة مكان تثبيت الإصدار المخصص من Tomcat. يمكنك تعيين موقع التثبيت في إعداد تطبيق CATALINA_BASE.

يمكنك استخدام Azure CLI لتغيير هذا الإعداد:

    az webapp config appsettings set -g $MyResourceGroup -n $MyUniqueApp --settings CATALINA_BASE="%LOCAL_EXPANDED%\tomcat"

أو يمكنك تغيير الإعداد يدوياً في مدخل Azure:

1. انتقل إلىالإعدادات>التكوين>إعدادات التطبيق.
2. حددإعداد تطبيق جديد.
3. استخدم هذه القيم لإنشاء الإعداد:
   1. الاسم: CATALINA_BASE
   2. القيمة: "%LOCAL_EXPANDED%\tomcat"

إنهاء التكوين

وأخيرا، يمكنك وضع برنامج التشغيل JARs في مسار فئة Tomcat وإعادة تشغيل App Service. تأكد من أن ملفات برنامج تشغيل JDBC متوفرة لمحمل فئة Tomcat عن طريق وضعها في الدليل /home/site/lib . في Cloud Shell، قم بتشغيل az webapp deploy --type=lib لكل برنامج تشغيل JAR:

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --target-path <jar-name>.jar

توجد ثلاث خطوات أساسية عند تسجيل مصدر بيانات باستخدام JBoss EAP: تحميل برنامج تشغيل JDBC، وإضافة برنامج تشغيل JDBC باعتباره وحدة نمطية، وتسجيل الوحدة النمطية. App Service خدمة استضافة عديمة الحالة، لذلك يجب كتابة أوامر التكوين من أجل إضافة الوحدة النمطية لمصدر البيانات وتسجيلها وتطبيقها عند بدء تشغيل الحاوية.

1. احصل على برنامج تشغيل JDBC لقاعدة بياناتك.

2. أنشئ ملف XML لتعريف الوحدة النمطية لبرنامج تشغيل JDBC. يوضح المثال التالي تعريف وحدة نمطية ل PostgreSQL.

   <?xml version="1.0" ?>
   <module xmlns="urn:jboss:module:1.1" name="org.postgres">
       <resources>
       <!-- ***** IMPORTANT : REPLACE THIS PLACEHOLDER *******-->
       <resource-root path="/home/site/deployments/tools/postgresql-42.2.12.jar" />
       </resources>
       <dependencies>
           <module name="javax.api"/>
           <module name="javax.transaction.api"/>
       </dependencies>
   </module>
   

3. ضع أوامر JBoss CLI في ملف يسمى jboss-cli-commands.cli. يجب أن تضيف أوامر JBoss الوحدة النمطية وتسجلها باعتبارها مصدراً للبيانات. يوضح المثال التالي أوامر JBoss CLI ل PostgreSQL.

   #!/usr/bin/env bash
   module add --name=org.postgres --resources=/home/site/deployments/tools/postgresql-42.2.12.jar --module-xml=/home/site/deployments/tools/postgres-module.xml
   
   /subsystem=datasources/jdbc-driver=postgres:add(driver-name="postgres",driver-module-name="org.postgres",driver-class-name=org.postgresql.Driver,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
   
   data-source add --name=postgresDS --driver-name=postgres --jndi-name=java:jboss/datasources/postgresDS --connection-url=${POSTGRES_CONNECTION_URL,env.POSTGRES_CONNECTION_URL:jdbc:postgresql://db:5432/postgres} --user-name=${POSTGRES_SERVER_ADMIN_FULL_NAME,env.POSTGRES_SERVER_ADMIN_FULL_NAME:postgres} --password=${POSTGRES_SERVER_ADMIN_PASSWORD,env.POSTGRES_SERVER_ADMIN_PASSWORD:example} --use-ccm=true --max-pool-size=5 --blocking-timeout-wait-millis=5000 --enabled=true --driver-class=org.postgresql.Driver --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --jta=true --use-java-context=true --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
   

4. أنشئ برنامجاً نصياً لبدء التشغيل، startup_script.sh الذي يستدعي أوامر JBoss CLI. يوضح المثال التالي كيفية استدعاء .jboss-cli-commands.cli لاحقا، ستقوم بتكوين App Service لتشغيل هذا البرنامج النصي عند بدء تشغيل الحاوية.

   $JBOSS_HOME/bin/jboss-cli.sh --connect --file=/home/site/deployments/tools/jboss-cli-commands.cli
   

5. باستخدام عميل FTP من اختيارك، قم بتحميل برنامج تشغيل JDBC وjboss-cli-commands.cli وstartup_script.shوتعريف الوحدة النمطية إلى /site/deployments/tools/.

6. قم بتكوين موقعك لتشغيل startup_script.sh عند بدء تشغيل الحاوية. في مدخل Azure، انتقل إلىالتكوين>الإعدادات العامة>أمر بدء التشغيل. عيّن حقل أمر بدء التشغيل على /home/site/deployments/tools/startup_script.sh. احفظ تغييراتك.

للتأكد من إضافة مصدر البيانات إلى خادم JBoss، استخدم SSH في تطبيق الويب وقم بتشغيل $JBOSS_HOME/bin/jboss-cli.sh --connect. بمجرد الاتصال ب JBoss، قم بتشغيل /subsystem=datasources:read-resource لطباعة قائمة بمصادر البيانات.

الخطوات التالية

تفضل بزيارة مركز Azure لمطوري برامج Java للعثور على التشغيل السريع لـ Azure والبرامج التعليمية ووثائق Java المرجعية.

• الأسئلة الشائعة حول App Service بنظام Linux
• متغيرات البيئة ومرجع إعدادات التطبيق