Jak utworzyć objaśnienie w języku Java

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X.
Informacje

Co to jest objaśnienie Java?

Apigee Edge udostępnia szereg zasad, które spełniają typowe wymagania związane z zarządzaniem interfejsami API, takimi jak zabezpieczenia, przekształcanie danych czy zarządzanie ruchem.

Istnieją jednak sytuacje, w których interfejs API wymaga niestandardowego działania, które nie jest zaimplementowane w standardowej zasadzie. W takich przypadkach Apigee udostępnia kilka opcji, które umożliwiają opracowanie skryptu lub kodu niestandardowego działania interfejsu API. Jednym ze sposobów jest zaimplementowanie oczekiwanego zachowania w Javie.

Informacje o obsługiwanych wersjach Javy znajdziesz w sekcji Obsługiwane oprogramowanie i obsługiwane wersje.

Jak używać kodu Java na serwerze proxy?

Zasada objaśnień Java umożliwia wywoływanie kodu Java z poziomu wykonywanego przepływu serwera proxy. W Twoim kodzie Java muszą być wdrożone określone interfejsy Java przeznaczone do obsługi brzegowej, które umożliwiają kodowi interakcję z uruchomionym serwerem proxy. Istnieją na przykład metody Java do pobierania i ustawiania nagłówków, parametrów zapytań, zmiennych przepływu i innych elementów w bieżącym kontekście procesu serwera proxy.

Kiedy należy użyć objaśnienia w Javie?

Przyjrzyjmy się sytuacjom, w których przydają się objaśnienia Java, oraz sytuacje, w których warto rozważyć inne rozwiązania.

Po pierwsze, weź pod uwagę alternatywne podejścia

Zanim użyjesz objaśnienia w Javie, pamiętaj, że możesz go zastąpić innymi metodami. Na przykład:

  • W przypadku lekkich operacji, takich jak wywołania interfejsu API HTTP do usług zdalnych, rozważ użycie zasady ServiceCallout. Zapoznaj się z zasadami dotyczącymi objaśnień usługi.
  • 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, możesz użyć języka JavaScript lub Pythona.

Funkcje dostępne w kodzie Java

Objaśnienie w Javie obsługuje następujące operacje podstawowe:

  • analizowanie żądań i wiadomości z odpowiedziami oraz manipulowanie nimi;
  • Pobieranie i ustawianie zmiennych przepływu. Aby uzyskać dostęp do zmiennych przepływu Edge, możesz użyć metod Java. Jeśli chcesz uzyskać dostęp do informacji mapy klucz-wartość (KVM), użyj zasady KVM, przypisz wartości KVM do zmiennych przepływu, a potem będziesz mieć dostęp do zmiennych przepływu z wywołania Javy.
  • Nawiązywanie połączeń z usługami zewnętrznymi
  • Uszkodzenia górne
  • Manipulowanie komunikatami o błędach i kodami stanu

Czego nie można robić w kodzie Java

Większość wywołań systemowych jest zabroniona. Nie możesz:

  • Umożliwia odczyty lub zapisy w wewnętrznym systemie plików. Oznacza to, że nie możesz używać żadnych pakietów Javy do odczytu i zapisu w wewnętrznych systemach plików, ale możesz wykonywać zdalne wywołania zewnętrzne.
  • Uzyskaj informacje o bieżącym procesie, liście procesów lub wykorzystaniu procesora/pamięci na maszynie.
  • Uzyskaj dostęp do kodu źródłowego w plikach „expressions-1.0.0.jar” i „message-flow-1.0.0.jar”.

Chociaż niektóre z takich wywołań mogą działać, nie są obsługiwane i w każdej chwili możemy je aktywnie wyłączyć. Unikaj wykonywania takich wywołań w kodzie.

Nie używaj bibliotek Javy dołączonych do Apigee Edge ani nie polegaj na nich. Te biblioteki służą tylko do korzystania z funkcji usługi Edge i nie ma gwarancji, że biblioteka będzie dostępna od początku do publikacji. Jeśli używasz takich bibliotek, używaj ich tylko w prezentacjach nieprodukcyjnych.

Objaśnienie Hello w języku Java

Omówmy podstawowy przykład objaśnienia hello world w Javie. W tym przykładzie tworzymy prosty serwer proxy z wywołaniem w Javie, które zwraca odpowiedź „hello world”. Serwer proxy może zwrócić jedną z dwóch możliwych odpowiedzi:

  • Jeśli przekażesz nagłówek „username” z wartością „name”, serwer proxy zwróci:

    Hello, <name>!
    
  • Jeśli pominiesz nagłówek, serwer proxy zwróci tylko:

    "Hello, Guest!"
    

Pobierz projekt startowy

Dla uproszczenia przygotowaliśmy dla Ciebie podstawowy projekt na GitHubie w repozytorium Apigee api-platform-samples.

  1. Pobierz lub skopiuj parametr api-platform-samples do swojego systemu.
  2. W wybranym terminalu lub edytorze kodu otwórz projekt api-platform-samples/doc-samples/java-hello.

Pisanie kodu Java

  1. Otwórz źródłowy plik Java: java-hello/callout/src/main/java/HelloJava.java. Ten plik to szkieletowa wersja głównej klasy Java, którą zaimplementujemy. Zaimportowane pakiety są wymagane dla kodu objaśnienia Edge w Javie. Te klasy udostępniają metody umożliwiające dostęp do kontekstu wykonywania serwera proxy. Wkrótce omówimy kolejne etapy kompilowania i wdrażania tego kodu.
    package com.apigeesample;
    
    import com.apigee.flow.execution.ExecutionContext;
    import com.apigee.flow.execution.ExecutionResult;
    import com.apigee.flow.execution.spi.Execution;
    import com.apigee.flow.message.MessageContext;
    
    
    public class HelloJava implements Execution {
    
            public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
                    
                    try {
    
                            // Your code here.
                
                return ExecutionResult.SUCCESS;
    
                    } catch (Exception e) {
                            return ExecutionResult.ABORT;
                    }
            }
    
    }
    
  2. Zastąp komentowany wiersz // Your code here tym kodem:

    String name = messageContext.getMessage().getHeader("username");
    
    if (name != null && name.length()>0) {
            messageContext.getMessage().setContent("Hello, " + name + "!");
            messageContext.getMessage().removeHeader("username");
    } else {
            messageContext.getMessage().setContent("Hello, Guest!");
    }
    
  3. Zapisz plik.


Skompiluj kod za pomocą narzędzia Maven

Projekt jest skonfigurowany tak, aby można było skompilować projekt w narzędziu Maven. Jeśli chcesz użyć funkcji javac, użyjemy przykładu zgodnego z przykładem z narzędzia Maven.

  1. Sprawdź, czy masz zainstalowaną aplikację Maven:

    mvn -version
    
  2. Uruchom skrypt java-hello/buildsetup.sh. Ten skrypt instaluje wymagane zależności JAR w lokalnym repozytorium Maven.
  3. cd do katalogu java-hello/callout.
  4. Wykonaj Maven:

    mvn clean package
    
  5. Jeśli chcesz, sprawdź, czy plik JAR edge-custom-policy-java-hello.jar został skopiowany do java-hello/apiproxy/resources/java. To jest wymagana lokalizacja plików JAR, które chcesz wdrożyć za pomocą serwera proxy.

Kompilacja za pomocą języka javac (opcjonalnie)

W poprzedniej sekcji automatycznie wygenerujesz wymagany plik JAR Javy przy użyciu polecenia Maven. Jeśli do skompilowania kodu chcesz użyć narzędzia javac, możesz to zrobić w podobny sposób (z katalogu java-hello). Wymagane pliki JAR znajdziesz w katalogu java-hello/lib.

  1. CD na api-platform-samples/doc-samples/java-hello.
  2. Upewnij się, że w ścieżce jest plik javac.

    javac -version
    
  3. Wykonaj to polecenie javac:

    javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java
    
    Spowoduje to utworzenie com/apigeesample/HelloJava.class.
  4. Utwórz w katalogu apiproxy/resources/java plik JAR zawierający skompilowaną klasę. To jest wymagana lokalizacja plików JAR, które chcesz wdrożyć za pomocą serwera proxy. Aby to zrobić, uruchom poniższe polecenie w katalogu java-hello (nie zapomnij kropki na końcu).

    jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
    

Wdrażanie i wywoływanie serwera proxy

Skrypt wdrażania znajduje się w katalogu ./java-hello. Ale zanim ją uruchomisz, musisz ją szybko skonfigurować.

  1. cd do api-platform-samples/doc-samples/java-hello
  2. Otwórz plik ../../setup/setenv.sh i edytuj go zgodnie z informacjami o Twoim koncie Apigee: nazwą użytkownika (adresem e-mail powiązanym z kontem), nazwą organizacji i domeną, której używasz do wykonywania wywołań zarządzania przez interfejs API. Na przykład w przypadku Edge Cloud domena to https://api.enterprise.apigee.com, ale Twoja domena może być inna, jeśli używasz Edge Private Cloud.
  3. Zapisz plik setenv.sh.
  4. Uruchom skrypt wdrożenia:

    ./deploy.sh
    
  5. Jeśli wdrożenie się powiedzie, wykonaj skrypt wywoływania:

    ./invoke.sh
    

    Skrypt wywołania wywołuje polecenie cURL, które wygląda tak:

    curl  http://$org-$env.$api_domain/java-hello -H "username:Will"
    

    Komunikat „Hello, Will!

    Możesz edytować skrypt invoke.sh, aby zmienić nazwę. Jeśli zmienisz wywołanie cURL, aby usunąć nagłówek, polecenie zwraca „Hello, Guest!”.

Informacje o serwerze proxy

Przyjrzyjmy się szybko zasadom używanym na tym serwerze proxy. Zwróć uwagę na to, gdzie umiejscowione są zasady w procesie serwera proxy i dlaczego.

Zasady przypisywania wiadomości

Zasady przypisywania wiadomości są dołączone do przepływu żądania ProxyEndpoint. Kopiuje nagłówek nazwy użytkownika z żądania i przypisuje go do odpowiedzi. Ta operacja pozwala za pomocą zasady dotyczącej objaśnień w Javie dołączonej do procesu odpowiedzi uzyskiwać dostęp do nagłówka nazwy użytkownika i tworzyć niestandardową treść odpowiedzi przy użyciu jego wartości.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">     
    <DisplayName>CopyHeader</DisplayName>     
    <Copy source="request">         
        <Headers>             
          <Header name="username"/>         
        </Headers>     
    </Copy>     
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>     
    <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

Zasady dotyczące objaśnień w języku Java

Zasada dotycząca objaśnień Java jest dołączona do procesu odpowiedzi. Dzieje się tak, ponieważ niestandardowy kod Java wprowadza zmiany w nagłówkach odpowiedzi i wiadomości. Element ClassName zasady określa klasę główną, która jest wykonywana przez zasadę. Element ResourceURL to nazwa pliku JAR, który został utworzony i dodany do katalogu resources/java serwera proxy.

<JavaCallout name="hello-java">         
    <ClassName>com.apigeesample.HelloJava</ClassName>         
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL> 
</JavaCallout>

Co musisz wiedzieć o objaśnieniach w Javie

Ważne uwagi związane z implementacją objaśnienia w Javie:

  • Importuje klasy z pakietów com.apigee.flow.execution i com.apigee.flow.message. Pakiety te muszą być zawarte w pliku JAR, który jest spakowany i wdrożony. Możesz przesłać plik Java JAR za pomocą edytora serwera proxy interfejsu zarządzania lub dodać go do katalogu /resources/java w serwerach proxy interfejsu API tworzonych lokalnie.
  • Implementuje interfejs wykonywania. Każdy kod w Javie wykonywany na serwerze proxy interfejsu API musi implementować Execution.
  • Zasada dotycząca objaśnień w języku Java nie zawiera rzeczywistego kodu. Zamiast tego zasada objaśnienia w języku Java odwołuje się do „zasobu” Javy, który należy spakować w pliku JAR.
  • Nazwy pakietów, których należy unikać: w objaśnieniach Java nie używaj nazw pakietów io.apigee ani com.apigee. Są one zarezerwowane i używane przez inne moduły Apigee.
  • Jeśli objaśnienie w Javie korzysta z dodatkowych bibliotek zewnętrznych w pakiecie jako niezależne pliki JAR, umieść te pliki JAR także w katalogu /resources/java, aby mieć pewność, że zostaną prawidłowo wczytane w czasie działania.
  • Jeśli jest wiele plików JAR, po prostu dodaj je jako zasoby dodatkowe. Nie musisz modyfikować konfiguracji zasad, aby odwoływać się do dodatkowych plików JAR. Wystarczy, że umieścisz je w obrębie /resources/java.
  • Więcej informacji o przesyłaniu plików JAR w języku Java znajdziesz w artykule Pliki zasobów.