ExtensionDescription politikası

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Bir uzantıyı API proxy'sine dahil etmek için ExtensionCallout politikasını kullanın.

Uzantılar, Apigee Edge'in dışında belirli bir kaynağa erişim sağlar. Kaynak, Cloud Storage veya Cloud Speech-to-Text gibi Google Cloud Platform hizmetleri olabilir. Ancak kaynak, HTTP veya HTTPS üzerinden erişilebilen herhangi bir harici kaynak olabilir.

Uzantılara genel bakış için Uzantılar nedir? başlıklı makaleyi inceleyin. Başlangıç eğitimi için Eğitim: Uzantı ekleme ve kullanma başlıklı makaleyi inceleyin.

ExtensionCallout politikasından bir uzantıya erişmeden önce, Apigee Edge kuruluşunuza zaten yüklenmiş bir uzantı paketinden uzantıyı eklemeniz, yapılandırmanız ve dağıtmanız gerekir.

Örnekler

Aşağıda, Cloud Logging uzantısıyla kullanılabilecek örnek bir politika gösterilmektedir:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Cloud Logging uzantısının kullanıldığı eksiksiz bir eğitim için Eğitim: Uzantıları kullanma başlıklı makaleyi inceleyin.

Kullanılabilir tüm uzantıların örnekleri için Uzantı referansına genel bakış başlıklı makaleyi inceleyin.

ExtensionCallout politikası hakkında

Bir API proxy'sinden harici bir kaynağa erişmek için yapılandırılmış bir uzantıyı kullanmak istediğinizde ExtensionCallout politikasını kullanın.

Bu politikayı kullanmadan önce şunlara ihtiyacınız olacaktır:

• Bu politikadan erişmek istediğiniz harici kaynakla ilgili birkaç ayrıntı. Bu ayrıntılar kaynağa özeldir. Örneğin, politika Cloud Firestore veritabanınıza erişecekse oluşturmak veya erişmek istediğiniz koleksiyon ve doküman adını bilmeniz gerekir. Bu politikanın istek ve yanıt işleme yapılandırmasında genellikle kaynağa özgü bilgileri kullanırsınız.
• API proxy'nizin dağıtılacağı ortama eklenmiş, yapılandırılmış ve dağıtılmış bir uzantı. Başka bir deyişle, bu politikayı belirli bir Google Cloud hizmetine erişmek için kullanacaksanız ortamınızda bu hizmet için dağıtılmış bir uzantı bulunmalıdır. Yapılandırma ayrıntıları genellikle kaynağa erişimi daraltmak için gereken bilgileri (ör. proje kimliği veya hesap adı) içerir.

PostClientFlow'da ExtensionCallout politikasını kullanma

ExtensionCallout politikasını bir API proxy'sinin PostClientFlow'undan çağırabilirsiniz. PostClientFlow, yanıtı isteyen istemciye gönderdikten sonra yürütülür. Bu sayede, tüm metriklerin günlüğe kaydedilmesi sağlanır. PostClientFlow'u kullanmayla ilgili ayrıntılar için API proxy yapılandırma referansı başlıklı makaleyi inceleyin.

Google Cloud Logging uzantısını PostClientFlow'dan çağırmak için ExtensionCallout politikasını kullanmak istiyorsanız kuruluşunuzda features.allowExtensionsInPostClientFlow işaretinin true olarak ayarlandığından emin olun.

• Apigee Edge for Public Cloud müşterisiyseniz features.allowExtensionsInPostClientFlow işareti varsayılan olarak true olarak ayarlanır.

• Apigee Edge for Private Cloud müşterisiyseniz features.allowExtensionsInPostClientFlow işaretini true olarak ayarlamak için Update organization properties API'sini kullanın.

PostClientFlow'dan MessageLogging politikası çağrısıyla ilgili tüm kısıtlamalar ExtensionCallout politikası için de geçerlidir. Daha fazla bilgi için Kullanım notları bölümüne bakın.

Öğe referansı

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

<ConnectorCallout> özellikleri

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

Aşağıdaki tabloda tüm politika üst öğelerinde ortak olan özellikler açıklanmaktadır:

&lt;DisplayName&gt; öğe

Politikayı name özelliğine ek olarak farklı bir doğal dil adına sahip yönetim arayüzü proxy düzenleyicisi.

<DisplayName>Policy Display Name</DisplayName>

<Action> öğesi

Politikanın çağrılması gereken, uzantı tarafından kullanıma sunulan işlem.

<Action>action-exposed-by-extension</Action>

Her uzantı, kendi işlem grubunu kullanıma sunar. Bu işlemler, uzantının temsil ettiği kaynağın işlevlerine erişim sağlar. Bir işlemi, <Input> öğesinin içeriğini kullanarak işlevin bağımsız değişkenlerini belirlediğiniz ve bu politikayla çağırdığınız bir işlev olarak düşünebilirsiniz. İşlemin yanıtı, <Output> öğesiyle belirttiğiniz değişkende saklanır.

Uzantının işlevlerinin listesi için bu politikadan çağırdığınız uzantının referansına bakın.

<Connector> öğesi

Kullanılacak yapılandırılmış uzantının adı. Bu, bir ortama dağıtım için yapılandırıldığında uzantıya verilen ortama kapsamlı addır.

<Connector>name-of-configured-extension</Connector>

Bir uzantının, aynı uzantı paketine dayalı olarak dağıtılan başka bir uzantıdan farklı olabilecek yapılandırma değerleri vardır. Bu yapılandırma değerleri, aynı paketten yapılandırılan uzantılar arasındaki çalışma zamanı işlevselliğinde önemli farklılıkları temsil edebilir. Bu nedenle, çağrılacak doğru uzantıyı belirttiğinizden emin olun.

<Input> öğesi

Uzantıya gönderilecek istek gövdesini içeren JSON.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Bu, temelde <Action> öğesiyle belirttiğiniz işleme yönelik bir argümandır. <Input> öğesinin değeri, uzantıya ve çağırdığınız işleme bağlı olarak değişir. Her işlemin özellikleri hakkında ayrıntılı bilgi için uzantı paketi belgelerine bakın.

Birçok <Input> öğe değeri, <![CDATA[]]> bölümü olarak eklenmeden doğru şekilde çalışır. Ancak JSON kuralları, XML olarak ayrıştırılmayacak değerlere izin verir. En iyi uygulama olarak, çalışma zamanında ayrıştırma hatalarını önlemek için JSON'ı CDATA bölümü olarak ekleyin.

<Input> öğesinin değeri, özellikleri çağrılacak uzantı işlemine gönderilecek değerleri belirten iyi biçimlendirilmiş bir JSON'dur. Örneğin, Google Cloud Logging Extension uzantısının log işlemi, yazılacak günlüğü (logName), girişe eklenecek meta verileri (metadata) ve günlük mesajını (data) belirten değerleri alır. İşte bir örnek:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

<Input> JSON'da akış değişkenlerini kullanma

<Input> içeriği, ileti şablonu olarak değerlendirilir. Bu, küme parantezleri içine alınmış bir değişken adının çalışma zamanında, referans verilen değişkenin değeriyle değiştirileceği anlamına gelir.

Örneğin, API proxy'sini çağıran istemcinin IP adresini almak için önceki <Input> bloğunu client.ip akış değişkenini kullanacak şekilde yeniden yazabilirsiniz:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

JSON'daki bir özellik değerinin çalışma zamanında tırnak işaretleri içine alınmasını istiyorsanız JSON kodunuzda tırnak işaretleri kullandığınızdan emin olun. Bu durum, çalışma zamanında çözümlenecek bir JSON özelliği değeri olarak akış değişkeni belirttiğinizde de geçerlidir.

Aşağıdaki <Input> örneğinde iki akış değişkeni referansı bulunmaktadır:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

Çalışma zamanında JSON özelliği değerleri aşağıdaki gibi çözümlenir:

• logName özellik değeri: dize değişmezi example-log.
• metadata mülk değeri: my.log.entry.metadata akış değişkeni değeri, tırnak işaretleri olmadan. Bu, değişkenin değeri bir nesneyi temsil eden JSON ise yararlı olabilir.
• message özelliği değeri: client.ip akış değişkeni değeri, tırnak işaretleri ile birlikte.

<Output> öğesi

Uzantı işleminin yanıtını depolayan bir değişkenin adı.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

veya

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Yanıt alındığında, yanıt değeri burada belirttiğiniz değişkene yerleştirilir. Bu değişkene diğer API proxy kodundan erişebilirsiniz.

Uzantı yanıtı nesneleri JSON biçimindedir. Politikanın JSON'u nasıl işleyeceğiyle ilgili iki seçenek vardır:

• Ayrıştırılmış (varsayılan): Politika, JSON nesnesini ayrıştırır ve JSON verileriyle otomatik olarak değişkenler oluşturur. Örneğin, JSON "messageId" : 12345; içeriyorsa ve çıktı değişkeninizi extensionOutput olarak adlandırırsanız {extensionOutput.messageId} değişkenini kullanarak diğer politikalarda bu ileti kimliğine erişebilirsiniz.
• Ayrıştırılmamış: Çıkış değişkeni, uzantıdan gelen ham ve ayrıştırılmamış JSON yanıtını içerir. (İsterseniz JavaScript politikası kullanarak yanıt değerini ayrı bir adımda ayrıştırmaya devam edebilirsiniz.)

<Output> Özellikleri

Akış değişkenleri

Yok.

Hata kodları

Apigee Edge politikalarından döndürülen hatalar, Politika hatası referansı bölümünde açıklandığı gibi tutarlı bir biçime sahiptir.

Bu bölümde, bu politika bir hata tetiklediğinde ayarlanan hata mesajları ve akış değişkenleri açıklanmaktadır. Bu bilgiler, bir proxy için hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme konularına göz atın.

Çalışma zamanı hataları

Bu hatalar, politika yürütüldüğünde ortaya çıkabilir.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda oluşabilir.