Zasady dotyczące objaśnienia Java

Oglądasz dokumentację Apigee Edge.
Wyświetl dokumentację Apigee X.

Co

Umożliwia korzystanie z Javy w celu implementowania niestandardowego zachowania, które nie jest stosowane w zasadach Apigee. W kodzie Java masz dostęp do właściwości wiadomości (nagłówków, parametrów zapytania, treści) i zmiennych przepływu w przepływie proxy. Jeśli dopiero zaczynasz korzystać z tej zasady, przeczytaj, jak utworzyć objaśnienie w języku Java.

Obsługiwane wersje środowiska Java znajdziesz w artykule Obsługiwane oprogramowanie i obsługiwane wersje.

Kiedy

Wskazówki znajdziesz w sekcji „Kiedy należy użyć objaśnienia Java?” w artykule Jak utworzyć objaśnienie dotyczące języka Java.

Informacje

Zasada Objaśnienia w języku Java umożliwia m.in. pobieranie i ustawianie zmiennych przepływu, wykonywanie logiki niestandardowej oraz obsługę błędów, wyodrębnianie danych z żądań i odpowiedzi. Ta zasada pozwala wdrożyć niestandardowe zachowanie, które nie jest objęte innymi standardowymi zasadami Edge.

Możesz spakować swoją aplikację Java do dowolnego pakietu plików JAR. Pamiętaj, że przy użyciu objaśnienia Javy obowiązują pewne ograniczenia. Ich listę znajdziesz w sekcji Ograniczenia.

Sample

Prosty przykład

Jak utworzyć objaśnienie w języku Java

Pobieranie właściwości w kodzie Java

Element <Property> zasady pozwala określić parę nazwa/wartość, którą można pobrać w czasie działania w kodzie Java. Praktyczny przykład, który korzysta z właściwości, znajdziesz w artykule Jak używać właściwości w objaśnieniu Java.

Użyj atrybutu name elementu <Property>, aby określić nazwę, przy użyciu której uzyskasz dostęp do właściwości z kodu Java. Wartość elementu <Property> (wartość między otwierającym a zamykającym tagiem) to wartość, którą otrzyma kod Java. Wartość musi być ciągiem tekstowym. Nie można się odwoływać do zmiennej przepływu, aby uzyskać wartość.

  • Skonfiguruj usługę. W tym miejscu wartością właściwości jest nazwa zmiennej response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • W kodzie Java zaimplementuj ten konstruktor w implementacji klasy wykonania w ten sposób:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Ustawianie zmiennych przepływu w kodzie Java

Dokładny opis sposobu ustawiania zmiennych w kontekście komunikatu (zmiennej przepływu) w kodzie Java znajdziesz w tym poście na karcie Apigee na karcie Społeczność.

Dokumentacja elementu

Odwołanie do elementu opisuje elementy i atrybuty zasady JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Atrybuty <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

Tabela poniżej opisuje atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

Atrybut Opis Domyślnie Obecność
name

Wewnętrzna nazwa zasady. Wartość atrybutu name może zawierać litery, cyfry, spacje, łączniki, podkreślenia i kropki. Ta wartość nie może przekraczać 255 znaków.

Opcjonalnie użyj elementu <DisplayName>, aby oznaczyć zasadę w edytorze proxy interfejsu zarządzania inną nazwą w języku naturalnym.

 Nie dotyczy Wymagany
continueOnError

Ustaw wartość false, aby wyświetlać błąd, gdy zasada nie działa. To prawidłowy proces w przypadku większości zasad.

Ustaw wartość true, aby kontynuować wykonywanie przepływu nawet po naruszeniu zasady.

 fałsz Opcjonalnie
enabled

Ustaw jako true, aby egzekwować zasadę.

Ustaw zasadę false, aby wyłączyć tę zasadę. Zasada nie będzie egzekwowana, nawet jeśli pozostanie powiązana z przepływem.

 prawda Opcjonalnie
async

Ten atrybut został wycofany.

 fałsz Wycofano

Element <DisplayName>

Używaj atrybutu name tak, aby oznaczyć zasadę w edytorze proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>
Domyślnie

Nie dotyczy

Jeśli pominiesz ten element, zostanie użyta wartość atrybutu name zasady.
Obecność Opcjonalnie
Typ Ciąg znaków

Element <ClassName>

Określa nazwę klasy Java, która jest wykonywana po uruchomieniu zasady objaśnienia Java. Klasa musi być uwzględniona w pliku JAR określonym przez <ResourceURL>. Przeczytaj też, jak utworzyć objaśnienie w języku Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Domyślne: Nie dotyczy
Obecność: Wymagany
Typ: Ciąg znaków

Element <Property>

Określa właściwość, do której możesz uzyskać dostęp z kodu Java w czasie działania. Musisz określić wartość literału dla każdej właściwości. W tym elemencie nie możesz odwoływać się do zmiennych przepływu. Działający przykład, który korzysta z właściwości, znajdziesz w artykule Jak używać właściwości w objaśnieniu Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Domyślne: Brak
Obecność: Opcjonalnie
Typ: Ciąg znaków

Atrybuty

Atrybut Opis Domyślna Obecność
nazwa

Określa nazwę właściwości.

 Nie dotyczy Wymagany.

<ResourceURL>

Ten element określa plik JAR w języku Java, który będzie wykonywany po uruchomieniu zasady objaśnień Java.

Możesz przechowywać ten plik w zakresie serwera proxy interfejsu API (w sekcji /apiproxy/resources/java w pakiecie proxy interfejsu API, w sekcji Skrypty w panelu nawigatora proxy interfejsu API) lub w zakresie organizacji lub środowiska do ponownego użycia na wielu serwerach proxy interfejsu API zgodnie z opisem w plikach zasobów.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Domyślne: Brak
Obecność: Wymagany
Typ: Ciąg znaków

Dokumentacja błędu

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, a także wartości zmiennych ustawionych przez Edge w momencie aktywowania tej zasady. Ta informacja jest ważna, gdy opracowujesz reguły obsługi błędów. Więcej informacji znajdziesz w artykułach Co musisz wiedzieć o błędach zasad i Obsługa błędów.

Błędy w czasie wykonywania

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

Kod błędu Stan HTTP Przyczyna Napraw
steps.javacallout.ExecutionError 500 Błąd występuje, gdy kod Java zwróci wyjątek lub zwróci wartość null podczas wykonywania zasady JavaCallout.

Błędy wdrażania

Te błędy mogą wystąpić, gdy serwer proxy zawierający zasadę jest wdrożony.

Nazwa błędu Ciąg znaków błędu Stan HTTP Występuje, gdy
ResourceDoesNotExist Resource with name [name] and type [type] does not exist Nie dotyczy Plik określony w elemencie <ResourceURL> nie istnieje.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] Nie dotyczy Pliku klasy określonego w elemencie <ClassName> nie ma w zasobniku.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] Nie dotyczy Zobacz ciąg znaków błędu. Zobacz też Obsługiwane oprogramowanie i obsługiwane wersje.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] Nie dotyczy Zobacz ciąg znaków błędu.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] Nie dotyczy Zobacz ciąg znaków błędu.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] Nie dotyczy Zobacz ciąg znaków błędu.
NoResourceForURL Could not locate a resource with URL [string] Nie dotyczy Zobacz ciąg znaków błędu.

Zmienne błędów

Zmienne te są ustawiane, gdy zasada powoduje błąd. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach zasad.

Zmienne Gdzie Przykład
fault.name="fault_name" fault_name to nazwa błędu, zgodnie z tabelą Błędy środowiska wykonawczego. Nazwa błędu jest ostatnią częścią kodu błędu. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name to określona przez użytkownika nazwa zasady, która spowodowała błąd. javacallout.JC-GetUserData.failed = true

Przykładowa odpowiedź na błąd

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Przykładowa reguła awarii

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Schematy

Kompilowanie i wdrażanie

Szczegółowe informacje o skompilowaniu niestandardowego kodu Java i wdrożeniu go za pomocą serwera proxy znajdziesz w tym artykule.

Ograniczenia

Podczas tworzenia objaśnień w Javie musisz wziąć pod uwagę poniższe ograniczenia:

  • Większość wywołań systemu jest niedozwolona. Na przykład nie można dokonywać odczytu ani zapisów w wewnętrznym systemie plików.
  • Dostęp do sieci za pomocą gniazd. Apigee ogranicza dostęp do adresów sitelocal, dowolne lokalne, zapętlenia i linków lokalnych.
  • Objaśnienie nie może uzyskać informacji o bieżącym procesie, liście procesów ani wykorzystaniu procesora/pamięci na komputerze. Część takich połączeń może działać, ale nie zawsze jest aktywna i może zostać w każdej chwili wyłączona. Aby zadbać o zgodność na potrzeby przekierowania, unikaj wykonywania takich wywołań w kodzie.
  • Korzystanie z bibliotek Java zawartych w Apigee Edge nie jest obsługiwane. Te biblioteki służą tylko do działania usługi Edge i nie ma gwarancji, że biblioteka będzie dostępna w poszczególnych wersjach.
  • W objaśnieniach Java nie używaj znaków io.apigee ani com.apigee jako nazw pakietów. Te nazwy są zarezerwowane i używane przez inne moduły Apigee.

Sposób prezentacji

Umieść JAR na serwerze proxy interfejsu API w sekcji /resources/java. Jeśli objaśnienie w Javie bazuje na dodatkowych bibliotekach innych firm spakowanych jako niezależne pliki JAR, umieść te pliki JAR w katalogu /resources/java również wtedy, gdy pliki te są prawidłowo wczytywane w czasie działania.

Jeśli do tworzenia lub modyfikowania serwera proxy używasz interfejsu zarządzania, dodaj nowy zasób i określ dodatkowy zależny plik JAR. Jeśli masz więcej niż jeden plik JAR, po prostu dodaj go jako dodatkowe zasoby. Nie musisz modyfikować konfiguracji zasad, aby odwołać się do dodatkowych plików JAR. Umieszczenie ich w polu /resources/java wystarczy.

Informacje o przesyłaniu plików JAR w języku Java znajdziesz w artykule Pliki zasobów.

Szczegółowe informacje o tym, jak przygotować i wdrożyć objaśnienie Javy za pomocą Maven lub javac, znajdziesz w artykule Tworzenie objaśnienia w Javie.

Javy

Dokument Java do tworzenia kodu objaśnienia Java jest dostępny tutaj na GitHubie. Musisz skopiować lub pobrać kod HTML do systemu, a następnie otworzyć plik index.html w przeglądarce.

Zastosowanie

  • Zasady dotyczące objaśnienia w języku Java nie zawierają rzeczywistego kodu. Zamiast tego zasada Objaśnienia w Javie odwołuje się do „zasobu” Javy i definiuje krok w procesie interfejsu API, w którym wykonywany jest kod Java. Plik JAR w języku Java możesz przesłać za pomocą edytora proxy serwera zarządzania interfejsami użytkownika lub umieścić go w katalogu /resources/java na serwerach proxy interfejsu API, które tworzysz lokalnie.
  • W przypadku prostych operacji, takich jak wywołania interfejsu API do usług zdalnych, zalecamy używanie zasady ServiceCallout. Zobacz zasady dotyczące objaśnień dotyczących usług.
  • W przypadku stosunkowo prostych interakcji z treścią wiadomości, takich jak modyfikowanie lub wyodrębnianie nagłówków, parametrów lub treści wiadomości, Apigee zaleca użycie zasady JavaScript.

Powiązane artykuły