حدد الموارد في بيان الخدمة

نظرة عامة

يتم تعريف تطبيقات وخدمات Service Fabric وتعيين إصداراتها باستخدام ملفات بيان التطبيقات. للحصول على نظرة عامة على مستوى أعلى حول ServiceManifest.xml وApplicationManifest.xml، راجع تطبيق Service Fabric وملفات بيان الخدمة.

يسمح بيان الخدمة بالإعلان عن الموارد التي تستخدمها الخدمة، أو تغييرها دون تغيير التعليمات البرمجية المحولة برمجيًا. يدعم Service Fabric تكوين موارد نقطة تقديم الخدمة. يمكن التحكم في الوصول إلى الموارد المحددة في بيان الخدمة عبر SecurityGroup في بيان التطبيق. يسمح إعلان الموارد بتغيير هذه الموارد في وقت التوزيع، مما يعني أن الخدمة لا تحتاج إلى إدخال آلية تكوين جديدة. يتم تثبيت تعريف المخطط لملف ServiceManifest.xml باستخدام حزمة SDK لـ Service Fabric والأدوات إلى C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd، ويتم توثيقه في وثائق المخطط ServiceFabricServiceModel.xsd.

نقاط النهاية

عند تعريف مورد نقطة النهاية في بيان الخدمة، يقوم Service Fabric بتعيين منافذ من نطاق منفذ التطبيق المحجوز في حال عدم تحديد منفذ بشكل صريح. على سبيل المثال، انظر إلى نقطة النهاية ServiceEndpoint1 المحددة في القصاصة البرمجية للبيان المتوفرة بعد هذه الفقرة. بالإضافة إلى ذلك، يمكن للخدمات أيضاً طلب منفذ معين في مورد. يمكن تعيين أرقام منافذ مختلفة للنسخ المتماثلة للخدمة التي تعمل على عقد نظام مجموعة مختلفة، بينما تشترك النسخ المتماثلة للخدمة التي تعمل على العقدة نفسها في المنفذ. يمكن للنسخ المتماثلة للخدمة بعد ذلك استخدام هذه المنافذ حسب الحاجة للنسخ المتماثل والاستماع لطلبات العميل.

عند تنشيط خدمة تحدد نقطة نهاية https، سيقوم Service Fabric بتعيين إدخال التحكم في الوصول للمنفذ، وربط شهادة الخادم المحددة بالمنفذ، وكذلك منح الهوية التي يتم تشغيلها كأذونات للمفتاح الخاص للشهادة. يتم استدعاء تدفق التنشيط في كل مرة يبدأ فيها Service Fabric، أو عند تغيير إعلان الشهادة الخاص بالتطبيق عبر ترقية. ستتم أيضاً مراقبة شهادة نقطة النهاية للتغييرات / التجديدات، وستتم إعادة تطبيق الأذونات بشكل دوري حسب الضرورة.

عند إنهاء الخدمة، سيقوم Service Fabric بتنظيف إدخال التحكم في الوصول إلى نقطة النهاية، وإزالة الشهادة الملزمة. ومع ذلك، لن يتم تنظيف أي أذونات مطبقة على المفتاح الخاص للشهادة.

تحذير

حسب التصميم، يجب ألا تتداخل المنافذ الثابتة مع نطاق منفذ التطبيق المُحدد في ClusterManifest. إذا قمت بتحديد منفذ ثابت، فقم بتعيينه خارج نطاق منفذ التطبيق، وإلا فسوف تنتج عنه تعارضات المنافذ. مع الإصدار 6.5CU2، سنصدر تحذيراً صحياً عندما نكتشف مثل هذا التعارض ولكن نسمح باستمرار التوزيع بالتزامن مع سلوك 6.5 المنقول. ومع ذلك، قد نمنع توزيع التطبيق من الإصدارات الرئيسية التالية.

مع الإصدار 7.0، سنقوم بإصدار تحذير سلامة عندما نكتشف تجاوز استخدام نطاق منفذ التطبيق HostingConfig::ApplicationPortExhaustThresholdPercentage(default 80%).

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint1" Protocol="http"/>
    <Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
    <Endpoint Name="ServiceEndpoint3" Protocol="https"/>
  </Endpoints>
</Resources>

إذا كانت هناك حزم تعليمات برمجية متعددة في حزمة خدمة واحدة، يجب أيضاً الرجوع إلى حزمة التعليمات البرمجية في قسم نقاط النهاية. على سبيل المثال، إذا كانت ServiceEndpoint2a وServiceEndpoint2b نقطتي نهاية من نفس حزمة الخدمة التي تشير إلى حزم تعليمات برمجية مختلفة، يتم توضيح حزمة التعليمات البرمجية المقابلة لكل نقطة نهاية كما يلي:

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint2a" Protocol="http" Port="802" CodePackageRef="Code1"/>
    <Endpoint Name="ServiceEndpoint2b" Protocol="http" Port="801" CodePackageRef="Code2"/>
  </Endpoints>
</Resources>

ارجع إلى تكوين خدمات موثوقة ذات حالة لقراءة المزيد حول الرجوع إلى نقاط النهاية من ملف إعدادات حزمة التكوين (settings.xml).

مثال: تحديد نقطة نهاية HTTP لخدمتك

يحدد بيان الخدمة التالي مورد نقطة نهاية TCP واحدًا وموردي نقطة نهاية HTTP في عنصر <الموارد>.

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="Stateful1Pkg"
                 Version="1.0.0"
                 xmlns="http://schemas.microsoft.com/2011/01/fabric"
                 xmlns:xsd="https://www.w3.org/2001/XMLSchema"
                 xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
  <ServiceTypes>
    <!-- This is the name of your ServiceType.
         This name must match the string used in the RegisterServiceType call in Program.cs. -->
    <StatefulServiceType ServiceTypeName="Stateful1Type" HasPersistedState="true" />
  </ServiceTypes>

  <!-- Code package is your service executable. -->
  <CodePackage Name="Code" Version="1.0.0">
    <EntryPoint>
      <ExeHost>
        <Program>Stateful1.exe</Program>
      </ExeHost>
    </EntryPoint>
  </CodePackage>

  <!-- Config package is the contents of the Config directory under PackageRoot that contains an
       independently updateable and versioned set of custom configuration settings for your service. -->
  <ConfigPackage Name="Config" Version="1.0.0" />

  <Resources>
    <Endpoints>
      <!-- This endpoint is used by the communication listener to obtain the port number on which to
           listen. Note that if your service is partitioned, this port is shared with
           replicas of different partitions that are placed in your code. -->
      <Endpoint Name="ServiceEndpoint1" Protocol="http"/>
      <Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
      <Endpoint Name="ServiceEndpoint3" Protocol="https"/>
      <Endpoint Name="ServiceEndpoint4" Protocol="https" Port="14023"/>

      <!-- This endpoint is used by the replicator for replicating the state of your service.
           This endpoint is configured through the ReplicatorSettings config section in the Settings.xml
           file under the ConfigPackage. -->
      <Endpoint Name="ReplicatorEndpoint" />
    </Endpoints>
  </Resources>
</ServiceManifest>

مثال: تحديد نقطة نهاية HTTP لخدمتك

يوفر بروتوكول HTTPS مصادقة الخادم، ويستخدم أيضاً لتشفير الاتصال بين العميل والخادم. لتمكين HTTPS على خدمة Service Fabric، حدد البروتوكول في قسم الموارد -> نقاط النهاية ->نقطة النهاية من بيان الخدمة، كما هو موضح سابقاً لـ ServiceEndpoint3.

ملاحظة

لا يمكن تغيير بروتوكول الخدمة أثناء ترقية التطبيق. إذا تم تغييره أثناء الترقية، فهذا تغيير مفاجئ.

تحذير

عند استخدام HTTPS، لا تستخدم المنفذ والشهادة نفسها لمثيلات خدمة مختلفة (مستقلة عن التطبيق) تم توزيعها على العقدة نفسها. ستؤدي ترقية خدمتين مختلفتين باستخدام المنفذ نفسه في مثيلات تطبيق مختلفة إلى فشل الترقية. للمزيد من المعلومات، راجع ترقية تطبيقات متعددة باستخدام نقاط نهاية HTTPS .

فيما يلي مثال على ApplicationManifest يوضح التكوين المطلوب لنقطة نهاية HTTPS. قد يتم الإعلان عن شهادة الخادم/نقطة النهاية بواسطة بصمة الإبهام أو الاسم الشائع للموضوع، ويجب توفير قيمة. EndpointRef هو مرجع إلى EndpointResource في ServiceManifest، ويجب تعيين البروتوكول الخاص به إلى بروتوكول "https". يمكنك إضافة أكثر من EndpointCertificate واحدة.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest ApplicationTypeName="Application1Type"
                     ApplicationTypeVersion="1.0.0"
                     xmlns="http://schemas.microsoft.com/2011/01/fabric"
                     xmlns:xsd="https://www.w3.org/2001/XMLSchema"
                     xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
  <Parameters>
    <Parameter Name="Stateful1_MinReplicaSetSize" DefaultValue="3" />
    <Parameter Name="Stateful1_PartitionCount" DefaultValue="1" />
    <Parameter Name="Stateful1_TargetReplicaSetSize" DefaultValue="3" />
  </Parameters>
  <!-- Import the ServiceManifest from the ServicePackage. The ServiceManifestName and ServiceManifestVersion
       should match the Name and Version attributes of the ServiceManifest element defined in the
       ServiceManifest.xml file. -->
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="Stateful1Pkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <Policies>
      <EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint3"/>
      <EndpointBindingPolicy CertificateRef="SslCertByCN" EndpointRef="ServiceEndpoint4"/>
    </Policies>
  </ServiceManifestImport>
  <DefaultServices>
    <!-- The section below creates instances of service types when an instance of this
         application type is created. You can also create one or more instances of service type by using the
         Service Fabric PowerShell module.

         The attribute ServiceTypeName below must match the name defined in the imported ServiceManifest.xml file. -->
    <Service Name="Stateful1">
      <StatefulService ServiceTypeName="Stateful1Type" TargetReplicaSetSize="[Stateful1_TargetReplicaSetSize]" MinReplicaSetSize="[Stateful1_MinReplicaSetSize]">
        <UniformInt64Partition PartitionCount="[Stateful1_PartitionCount]" LowKey="-9223372036854775808" HighKey="9223372036854775807" />
      </StatefulService>
    </Service>
  </DefaultServices>
  <Certificates>
    <EndpointCertificate Name="SslCertByTP" X509FindValue="FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F0" X509StoreName="MY" />  
    <EndpointCertificate Name="SslCertByCN" X509FindType="FindBySubjectName" X509FindValue="ServiceFabric-EndpointCertificateBinding-Test" X509StoreName="MY" />  
  </Certificates>
</ApplicationManifest>

بالنسبة لأنظمة مجموعات Linux، يتم تعيين مخزن MY افتراضيا إلى المجلد / var/lib/sfcerts.

للحصول على مثال على تطبيق كامل يستخدم نقطة نهاية HTTPS، راجع إضافة نقطة نهاية HTTPS إلى خدمة الواجهة الأمامية لواجهة برمجة تطبيقات الويب ASP.NET Core باستخدام Kestrel.

إعداد قائمة التحكم بالوصول إلى المنفذ لنقاط نهاية HTTP

سيقوم Service Fabric تلقائياً بتحديد نقاط نهاية HTTP(S) لقائمة التحكم بالوصول بشكل افتراضي. لن يقوم بإجراء إعداد قائمة التحكم بالوصول التلقائي إذا لم تحتو نقطة نهاية على SecurityAccessPolicy مقترنة بها، وتم تكوين Service Fabric ليتم تشغيله باستخدام حساب بامتيازات المسؤول.

تجاوز نقاط النهاية في ServiceManifest.xml

في ApplicationManifest، أضف قسم ResourceOverrides، والذي سيكون شقيقاً لقسم ConfigOverrides. في هذا القسم، يمكنك تحديد تجاوز القسم «نقاط النهاية» في قسم الموارد المحدد في «بيان الخدمة». يتم دعم نقاط النهاية المتجاوزة في وقت التشغيل 5.7.217/SDK 2.7.217 والإصدارات الأحدث.

من أجل تجاوز نقطة النهاية في ServiceManifest باستخدام ApplicationParameters، قم بتغيير ApplicationManifest على هذا النحو:

في القسم ServiceManifestImport، أضف قسماً جديداً "ResourceOverrides".

<ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="Stateless1Pkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <ResourceOverrides>
      <Endpoints>
        <Endpoint Name="ServiceEndpoint" Port="[Port]" Protocol="[Protocol]" Type="[Type]" />
        <Endpoint Name="ServiceEndpoint1" Port="[Port1]" Protocol="[Protocol1] "/>
      </Endpoints>
    </ResourceOverrides>
        <Policies>
           <EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint"/>
        </Policies>
  </ServiceManifestImport>

في قسم «المعلمات»، أضف أدناه:

  <Parameters>
    <Parameter Name="Port" DefaultValue="" />
    <Parameter Name="Protocol" DefaultValue="" />
    <Parameter Name="Type" DefaultValue="" />
    <Parameter Name="Port1" DefaultValue="" />
    <Parameter Name="Protocol1" DefaultValue="" />
  </Parameters>

أثناء توزيع التطبيق، يمكنك تمرير هذه القيم كـ «ApplicationParameters». على سبيل المثال:

PS C:\> New-ServiceFabricApplication -ApplicationName fabric:/myapp -ApplicationTypeName "AppType" -ApplicationTypeVersion "1.0.0" -ApplicationParameter @{Port='1001'; Protocol='https'; Type='Input'; Port1='2001'; Protocol='http'}

ملاحظة: إذا كانت القيمة المتوفرة لـ ApplicationParameter المحددة فارغة، فإننا نعود إلى القيمة الافتراضية المتوفرة في ServiceManifest لـ EndPointName المقابل.

على سبيل المثال:

إذا كنت قد حددت في ServiceManifest

  <Resources>
    <Endpoints>
      <Endpoint Name="ServiceEndpoint1" Protocol="tcp"/>
    </Endpoints>
  </Resources>

افترض أن قيمة Port1 وProtocol1 لمعلمات التطبيق فارغة أو خالية. سيتم تحديد المنفذ بواسطة ServiceFabric وسيكون «البروتوكول» هو TCP.

لنفترض أنك حددت قيمة خاطئة. لنفترض أنك حددت قيمة سلسلة "Foo" بدلاً من «int. New-ServiceFabricApplication»، فسيفشل الأمر ويعرض الخطأ: The override parameter with name 'ServiceEndpoint1' attribute 'Port1' in section 'ResourceOverrides' is invalid. The value specified is 'Foo' and required is 'int'.

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

توضح هذه المقالة كيفية تعريف نقاط النهاية في بيان خدمة Service Fabric. للحصول على أمثلة أكثر تفصيلاً، راجع:

أمثلة على ملفات بيان الخدمة والتطبيق

للحصول على إرشادات حول حزم تطبيق موجود وتوزيعه على نظام مجموعة Service Fabric، راجع:

حزم ملف قابل للتنفيذ موجود إلى Service Fabric وتوزيعه