Zasady dotyczące objaśnień w rozszerzeniach

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Aby włączyć rozszerzenie do serwera proxy interfejsu API, użyj zasady ExtensionCallout.

Rozszerzenie zapewnia dostęp do określonego zasobu zewnętrznego względem Apigee Edge. Zasobem mogą być usługi Google Cloud Platform, takie jak Cloud Storage czy Cloud Speech-to-Text. Może to być jednak dowolny zasób zewnętrzny dostępny przez HTTP lub HTTPS.

Omówienie rozszerzeń znajdziesz w artykule Co to są rozszerzenia? Wprowadzenie znajdziesz w samouczku Samouczek: dodawanie i używanie rozszerzenia.

Zanim uzyskasz dostęp do rozszerzenia z poziomu zasady ExtensionCallout, musisz dodać, skonfigurować i wdrożyć rozszerzenie z pakietu rozszerzeń, który jest już zainstalowany w Twojej organizacji Apigee Edge.

Przykłady

Poniżej znajduje się przykładowa zasada do użycia z rozszerzeniem Cloud Logging:

<?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>

Pełny samouczek dotyczący korzystania z rozszerzenia Cloud Logging znajdziesz w artykule Samouczek: korzystanie z rozszerzeń.

Przykłady wszystkich dostępnych rozszerzeń znajdziesz w omówieniu rozszerzeń.

Informacje o zasadzie ExtensionCallout

Użyj zasady ExtensionCallout, gdy chcesz użyć skonfigurowanego rozszerzenia, aby uzyskać dostęp do zasobu zewnętrznego z poziomu proxy interfejsu API.

Zanim zaczniesz korzystać z tych zasad, musisz mieć:

• Kilka szczegółów dotyczących zasobu zewnętrznego, do którego chcesz uzyskać dostęp na podstawie tych zasad. Te szczegóły będą dotyczyć konkretnego zasobu. Jeśli na przykład zasady będą uzyskiwać dostęp do bazy danych Cloud Firestore, musisz znać nazwę kolekcji i dokumentu, który chcesz utworzyć lub do którego chcesz uzyskać dostęp. Informacje dotyczące zasobów są zwykle używane do konfigurowania obsługi żądań i odpowiedzi w ramach tych zasad.
• Rozszerzenie dodane, skonfigurowane i wdrożone w środowisku, w którym zostanie wdrożony serwer proxy interfejsu API. Innymi słowy, jeśli chcesz użyć tych zasad, aby uzyskać dostęp do konkretnej usługi Google Cloud, w Twoim środowisku musi istnieć wdrożone rozszerzenie tej usługi. Szczegóły konfiguracji zwykle obejmują wymagane informacje, które pozwalają ograniczyć dostęp do zasobu, np. identyfikator projektu lub nazwę konta.

Używanie zasady ExtensionCallout w PostClientFlow

Zasady ExtensionCallout możesz wywołać z PostClientFlow proxy interfejsu API. Przepływ PostClientFlow jest wykonywany po wysłaniu odpowiedzi do klienta wysyłającego żądanie, co zapewnia dostępność wszystkich danych do rejestrowania. Więcej informacji o używaniu PostClientFlow znajdziesz w dokumentacji konfiguracji proxy interfejsu API.

Jeśli chcesz użyć zasady ExtensionCallout do wywołania rozszerzenia Google Cloud Logging z poziomu PostClientFlow, upewnij się, że w Twojej organizacji flaga features.allowExtensionsInPostClientFlow jest ustawiona na true.

• Jeśli jesteś klientem Apigee Edge na chmurę publiczną, flaga features.allowExtensionsInPostClientFlow jest domyślnie ustawiona na true.

• Jeśli jesteś klientem Apigee Edge for Private Cloud, użyj interfejsu Update organization properties API, aby ustawić flagę features.allowExtensionsInPostClientFlow na true.

Wszystkie ograniczenia dotyczące wywoływania zasad MessageLogging z zasad PostClientFlow mają również zastosowanie do zasad ExtensionCallout. Więcej informacji znajdziesz w sekcji Uwagi dotyczące użytkowania.

Dokumentacja elementu

<?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>

Atrybuty <ConnectorCallout>

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

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Action>

Działanie udostępniane przez rozszerzenie, które ma być wywoływane przez zasadę.

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

Każde rozszerzenie udostępnia własny zestaw działań, które zapewniają dostęp do funkcji zasobu, który reprezentuje. Działanie możesz traktować jako funkcję wywoływaną za pomocą tych zasad, która używa zawartości elementu <Input> do określania argumentów funkcji. Odpowiedź działania jest przechowywana w zmiennej określonej za pomocą elementu <Output>.

Listę funkcji rozszerzenia znajdziesz w dokumentacji rozszerzenia, z którego wywołujesz tę zasadę.

Element <Connector>

Nazwa skonfigurowanego rozszerzenia do użycia. Jest to nazwa rozszerzenia w zakresie środowiska, która została mu nadana podczas konfigurowania wdrożenia w środowisku.

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

Rozszerzenie ma wartości konfiguracji, które mogą się różnić od innego wdrożonego rozszerzenia opartego na tym samym pakiecie rozszerzenia. Te wartości konfiguracji mogą odzwierciedlać istotne różnice w funkcjonalności w czasie działania między rozszerzeniami skonfigurowanymi z tego samego pakietu, dlatego pamiętaj, aby określić prawidłowe rozszerzenie do wywołania.

Element <Input>

JSON zawierający treść żądania do wysłania do rozszerzenia.

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

Jest to argument działania określonego za pomocą elementu <Action>. Wartość elementu <Input> będzie się różnić w zależności od rozszerzenia i wywoływanego działania. Szczegółowe informacje o właściwościach poszczególnych działań znajdziesz w dokumentacji pakietu rozszerzeń.

Pamiętaj, że chociaż wiele wartości elementów <Input> będzie działać prawidłowo bez umieszczania ich w sekcji <![CDATA[]]>, reguły JSON dopuszczają wartości, które nie będą analizowane jako XML. Aby uniknąć błędów analizy w czasie działania, umieść kod JSON w sekcji CDATA.

Wartość elementu <Input> to prawidłowy plik JSON, którego właściwości określają wartości do wysłania do działania rozszerzenia w celu jego wywołania. Na przykład działanie log rozszerzenia Google Cloud Logging Extension przyjmuje wartości określające dziennik, do którego ma zostać zapisany log (logName), metadane do uwzględnienia we wpisie (metadata) i komunikat logu (data). Oto przykład:

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

Używanie zmiennych przepływu w <Input> JSON

Zawartość <Input> jest traktowana jako szablon wiadomości. Oznacza to, że nazwa zmiennej ujęta w nawiasy klamrowe zostanie w czasie działania programu zastąpiona wartością zmiennej, do której się odwołuje.

Możesz na przykład przepisać poprzedni blok <Input>, aby użyć zmiennej przepływu client.ip do uzyskania adresu IP klienta wywołującego proxy interfejsu API:

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

Jeśli chcesz, aby wartość właściwości w pliku JSON była w czasie działania programu ujęta w cudzysłów, użyj cudzysłowów w kodzie JSON. Dotyczy to również sytuacji, gdy jako wartość właściwości JSON określisz zmienną przepływu, która ma zostać rozwiązana w czasie działania.

Ten przykład <Input> zawiera 2 odwołania do zmiennych przepływu:

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

W czasie działania wartości właściwości JSON będą rozwiązywane w ten sposób:

• Wartość właściwości logName – literał ciągu example-log.
• wartość właściwości metadata – wartość zmiennej przepływu my.log.entry.metadata bez cudzysłowów. Może to być przydatne, jeśli wartość zmiennej jest sama w sobie plikiem JSON reprezentującym obiekt.
• Wartość właściwości message – wartość zmiennej przepływu client.ip z cudzysłowami.

Element <Output>

Nazwa zmiennej, która przechowuje odpowiedź działania rozszerzenia.

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

lub

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

Gdy otrzymasz odpowiedź, wartość reakcji zostanie umieszczona w określonej przez Ciebie zmiennej, do której możesz uzyskać dostęp z innego kodu proxy interfejsu API.

Obiekty odpowiedzi rozszerzenia są w formacie JSON. Zasady mogą obsługiwać plik JSON na 2 sposoby:

• Przetworzone (domyślnie): zasady analizują obiekt JSON i automatycznie generują zmienne z danymi JSON. Jeśli na przykład kod JSON zawiera "messageId" : 12345;, a zmienną wyjściową nazwiesz extensionOutput, możesz uzyskać dostęp do tego identyfikatora wiadomości w innych zasadach za pomocą zmiennej {extensionOutput.messageId}.
• Nieprzetworzona: zmienna wyjściowa zawiera nieprzetworzoną odpowiedź JSON z rozszerzenia. (Jeśli chcesz, możesz przeanalizować wartość odpowiedzi w osobnym kroku za pomocą zasad JavaScript).

Atrybuty <Output>

Zmienne przepływu

Brak.

Kody błędów

Błędy zwracane przez zasady Apigee Edge mają spójny format opisany w dokumentacji błędów zasad.

W tej sekcji znajdziesz komunikaty o błędach i zmienne przepływu, które są ustawiane, gdy zasada powoduje błąd. Ta informacja jest ważna, gdy opracowujesz reguły awarii serwera proxy. Aby dowiedzieć się więcej, przeczytaj artykuły Błędy w zasadach i Jak postępować w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić, gdy wdrażasz serwer proxy zawierający tę zasadę.